HTTP Referrer restrictions

HTTP Referrer ограничения являются одним из ключевых механизмов защиты API-ключей при работе с браузерными приложениями, использующими Google Maps JavaScript API в составе Google Maps Platform. Их основная задача — гарантировать, что ключ используется только с доверенных веб-сайтов, а не на сторонних или вредоносных ресурсах.

HTTP Referrer (или Referer) — это заголовок, который браузер автоматически добавляет к запросам, отправляемым с веб-страницы. Он содержит адрес страницы, с которой был инициирован запрос.

В контексте Google Maps JavaScript API этот механизм используется для проверки источника загрузки API:

  • запросы к Maps API идут из браузера
  • сервер Google получает домен страницы
  • сравнивает его с разрешённым списком referrer’ов
  • принимает или отклоняет запрос

Ключевая идея: API-ключ становится действительным только в пределах заданных доменов.

Типы ограничений API-ключа

В Google Maps Platform доступны разные стратегии ограничения ключей:

  • HTTP referrer restrictions (для браузера)
  • IP address restrictions (для серверов)
  • Android / iOS restrictions

Для Google Maps JavaScript API используется именно HTTP referrer ограничение, поскольку выполнение происходит в клиентском окружении.

Настройка HTTP Referrer restrictions

Ограничения задаются в панели управления API-ключами.

Типичная конфигурация включает список допустимых шаблонов:

https://example.com/*
https://*.example.com/*
http://localhost/*
http://127.0.0.1/*

Каждая строка — это шаблон, по которому Google определяет, разрешён ли запрос.

Поддерживаемые форматы шаблонов

HTTP referrer поддерживает несколько уровней гибкости:

1. Полный домен

https://example.com/*

Разрешает использование ключа только на основном домене.

2. Поддомены

https://*.example.com/*

Позволяет использовать API на любых поддоменах:

  • app.example.com
  • staging.example.com
  • api.example.com

3. Локальная разработка

http://localhost/*
http://127.0.0.1/*

Используется для тестирования без публикации проекта.

4. Ограничение по протоколу

Важно учитывать, что:

  • http и https считаются разными источниками
  • если указан только https, http будет отклонён

Механизм проверки referrer

При каждом запросе к Maps API происходит следующая последовательность:

  1. Браузер отправляет запрос с API-ключом

  2. Сервер Google получает:

    • API key
    • HTTP Referer header

  3. Система проверяет совпадение с разрешёнными шаблонами

  4. В случае несоответствия возвращается ошибка:

RefererNotAllowedMapError

или

ApiNotActivatedMapError

(в зависимости от конфигурации проекта)

Поведение при неправильной настройке

Некорректные referrer-ограничения приводят к частым проблемам:

  • карта не загружается
  • появляются серые блоки вместо карты
  • консоль содержит ошибки авторизации
  • квоты API не расходуются (запрос блокируется до выполнения)

Типичная ошибка:

This API project is not authorized to use this API key.

Особенности wildcard и поддоменов

Wildcard * работает только в пределах одной DNS-структуры.

Пример корректного использования:

https://*.example.com/*

Но важно:

  • нельзя использовать * в середине доменного имени произвольно
  • нельзя заменить произвольную часть протокола
  • нельзя использовать регулярные выражения

Допустимо:

  • https://*.site.com/*

Недопустимо:

  • https://sub.*.com/*

Различие между HTTP referrer и IP restrictions

HTTP referrer ограничения применяются в браузерных сценариях, тогда как IP restrictions используются для серверных API.

Тип ограничения Где используется Пример
HTTP referrer браузер Maps JS API
IP address backend / server Geocoding API
Android apps мобильные ключи Maps SDK
iOS apps мобильные ключи Maps SDK

Использование неправильного типа ограничения приводит к полной блокировке ключа.

Безопасность API-ключа в браузере

Поскольку JavaScript выполняется на клиенте, API-ключ неизбежно доступен пользователю. HTTP referrer ограничения не скрывают ключ, но ограничивают его применение.

Основные принципы защиты:

  • ключ всегда публичен, но ограничен доменом
  • нельзя полагаться на скрытие ключа
  • обязательна привязка к referrer
  • рекомендуется ограничивать только необходимыми доменами

Пример подключения с ограниченным ключом

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
  async
  defer
></script>

Если ключ имеет корректные HTTP referrer ограничения, карта загрузится только на разрешённом домене.

Поведение в SPA и динамических приложениях

В одностраничных приложениях (SPA) referrer обычно совпадает с основным доменом приложения. Однако возможны нюансы:

  • переходы внутри SPA не меняют referrer
  • но первый загрузочный URL критичен
  • при использовании iframe referrer может отличаться

Особенно важно учитывать:

  • приложения на React / Vue / Angular
  • SSR и гидратацию
  • загрузку Maps API после роутинга

Ошибки конфигурации, встречающиеся на практике

Наиболее частые проблемы:

1. Пропущенный протокол

example.com/*   ❌
https://example.com/* ✔

2. Отсутствие поддоменов

https://example.com/*   (не работает для www.example.com)

3. Несоответствие localhost

http://localhost:3000/* (порт может быть критичен)

В некоторых случаях необходимо явно учитывать порт разработки.

Рекомендации по настройке ограничений

  • использовать минимально необходимый набор доменов
  • разделять dev / staging / production ключи
  • регулярно проверять актуальность referrer списков
  • избегать использования широких wildcard без необходимости
  • контролировать ключи в панели Google Cloud Console

Диагностика проблем с referrer

При отладке полезно:

  • проверять заголовок Referer в DevTools
  • анализировать Network запросы к Maps API
  • сверять домен страницы и список разрешений
  • тестировать в режиме инкогнито (чистый cache/cookies)

Ошибки referrer почти всегда связаны не с API, а с несоответствием доменных шаблонов.

Поведение при отсутствии referrer

Некоторые сценарии могут приводить к отсутствию заголовка:

  • запросы из нестандартных WebView
  • строгие политики Referrer-Policy
  • локальные файлы file://

В таких случаях запросы могут быть отклонены независимо от корректности ключа.

Оглавление