Ограничения API ключа по домену и IP

API-ключ в Google Maps JavaScript API служит идентификатором проекта и используется для авторизации запросов к сервисам Google Maps Platform. По умолчанию любой, кто получил доступ к ключу, может попытаться использовать его для выполнения запросов от имени владельца проекта. Это создает риски:

• несанкционированного использования сервисов;
• роста расходов из-за чужих запросов;
• превышения квот;
• компрометации инфраструктуры приложения.

Для снижения этих рисков Google предоставляет механизм ограничений (Restrictions), позволяющий привязать ключ к определенным источникам запросов. Наиболее распространенными являются:

• ограничения по домену (HTTP Referrer Restrictions);
• ограничения по IP-адресам (IP Address Restrictions).

Правильная настройка ограничений считается обязательной практикой безопасности при работе с Google Maps Platform.

---

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

В настройках Google Cloud Console для каждого ключа можно выбрать один из вариантов ограничения источника запросов:

Тип ограничения	Назначение
None	Отсутствие ограничений
HTTP Referrers	Ограничение по доменам и страницам сайта
IP Addresses	Ограничение по IP-адресам серверов
Android Apps	Ограничение по приложениям Android
iOS Apps	Ограничение по приложениям iOS

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

---

Ограничения по домену (HTTP Referrer)

Принцип работы

Когда браузер загружает Google Maps JavaScript API, вместе с запросом передается HTTP-заголовок Referer. Он содержит адрес страницы, с которой выполняется загрузка.

Пример:

https://example.com/map.html

Google сравнивает значение Referer с настройками ключа.

Если домен разрешен, API загружается успешно.

Если домен отсутствует в списке разрешенных источников, появляется ошибка авторизации.

---

Где применяются ограничения по домену

Ограничения по домену используются для:

• публичных сайтов;
• интернет-магазинов;
• корпоративных порталов;
• CRM-систем с веб-интерфейсом;
• SPA-приложений на React, Vue, Angular;
• административных панелей.

Практически любой проект, использующий Google Maps JavaScript API в браузере, должен использовать именно этот тип ограничения.

---

Настройка ограничения по домену

После создания API-ключа в Google Cloud Console необходимо:

1. Открыть раздел Credentials.
2. Выбрать нужный API Key.
3. Перейти в блок Application Restrictions.
4. Выбрать пункт HTTP referrers.
5. Добавить разрешенные домены.

Примеры записей:

https://example.com/*

https://www.example.com/*

https://app.example.com/*

https://*.example.com/*

После сохранения изменений Google начинает применять ограничения к запросам.

---

Использование подстановочных символов

Для упрощения настройки допускается использование символа *.

Разрешение всех страниц домена

https://example.com/*

Разрешены:

https://example.com/
https://example.com/map
https://example.com/contact

---

Разрешение всех поддоменов

https://*.example.com/*

Разрешены:

https://app.example.com
https://crm.example.com
https://maps.example.com

---

Разрешение нескольких уровней поддоменов

https://*.example.com/*

Подходит также для:

https://dev.crm.example.com
https://api.dev.example.com

---

Ограничение конкретной страницей

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

Пример:

https://example.com/maps/*

Допустимые URL:

https://example.com/maps
https://example.com/maps/store
https://example.com/maps/search

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

https://example.com/catalog
https://example.com/blog

Подобный подход применяется редко, поскольку усложняет поддержку проекта.

---

Ограничение локальной разработки

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

Для localhost необходимо явно добавить адрес:

http://localhost/*

или

http://localhost:3000/*

Для различных инструментов разработки:

http://localhost:5173/*

http://localhost:8080/*

http://127.0.0.1/*

Без соответствующего разрешения карта не загрузится.

---

Типичные ошибки при ограничении по домену

Отсутствие WWW-версии

Разрешен только:

https://example.com/*

Но сайт открывается как:

https://www.example.com

Для Google это разные источники.

Необходимо добавить обе записи:

https://example.com/*

https://www.example.com/*

---

Неправильный протокол

Разрешено:

http://example.com/*

Фактический сайт работает через:

https://example.com/*

Google не считает такие адреса одинаковыми.

---

Неучтенный поддомен

Разрешено:

https://example.com/*

Но карта загружается с:

https://app.example.com

Требуется отдельное разрешение.

---

Кэширование настроек

После изменения ограничений обновление применяется не мгновенно.

Иногда требуется:

• несколько минут ожидания;
• очистка кэша браузера;
• повторная загрузка страницы.

---

Сообщения об ошибках

При неправильной настройке часто появляются ошибки вида:

RefererNotAllowedMapError

или

Google Maps JavaScript API error: RefererNotAllowedMapError

Это означает, что текущий домен отсутствует среди разрешенных источников.

---

Проверка текущего Referer

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

Запрос загрузки API выглядит примерно так:

https://maps.googleapis.com/maps/api/js?key=API_KEY

В его заголовках можно увидеть:

Referer: https://example.com/page

Именно это значение сравнивается с настройками ограничения.

---

Ограничения по IP-адресу

Назначение

Ограничения по IP используются для серверных приложений.

Google проверяет IP-адрес источника запроса и разрешает доступ только указанным адресам.

Пример разрешенного адреса:

203.0.113.15

Если запрос приходит с другого IP, доступ отклоняется.

---

Где применяются ограничения по IP

Ограничения по IP подходят для:

• Node.js-серверов;
• PHP-приложений;
• Java-сервисов;
• Python-бэкендов;
• микросервисов;
• серверных интеграций с геокодированием;
• фоновых процессов.

---

Почему IP-ограничения не подходят для JavaScript API

Google Maps JavaScript API работает в браузере пользователя.

Запросы выполняются не с сервера разработчика, а с компьютеров посетителей сайта.

Следовательно:

• IP каждого пользователя отличается;
• невозможно заранее перечислить все IP;
• карта перестанет работать.

Поэтому для JavaScript API рекомендуется использовать ограничения по домену, а не по IP.

---

Пример неправильной конфигурации

Предположим, сайт использует Google Maps JavaScript API:

<script
src="https://maps.googleapis.com/maps/api/js?key=API_KEY">
</script>

Для ключа задано ограничение:

198.51.100.10

Этот IP принадлежит серверу.

Однако карту открывает пользователь с адресом:

85.124.10.44

Проверка завершается ошибкой, поскольку запрос исходит не с серверного IP.

---

Когда используется отдельный ключ для сервера

Распространенная практика — разделение ключей.

Ключ для браузера

Ограничения:

HTTP Referrer Restrictions

Разрешенные домены:

https://example.com/*

Используется для:

• карт;
• маркеров;
• маршрутов;
• визуальных компонентов.

---

Ключ для сервера

Ограничения:

IP Address Restrictions

Разрешенные IP:

203.0.113.15
203.0.113.16

Используется для:

• Geocoding API;
• Places API на сервере;
• Distance Matrix API;
• фоновых вычислений.

Такой подход существенно повышает безопасность проекта.

---

Комбинирование ограничений с API Restrictions

Помимо ограничения источника запросов существует ограничение по набору доступных API.

В разделе API Restrictions можно указать, какие сервисы разрешено использовать через данный ключ.

Например:

Maps JavaScript API

или

Maps JavaScript API
Places API

Если злоумышленник получит ключ, он не сможет использовать его для других сервисов платформы.

---

Практический пример безопасной конфигурации

Ключ используется только для отображения карт на сайте.

Ограничение приложения

HTTP Referrer Restrictions

Разрешенные адреса:

https://example.com/*
https://www.example.com/*
https://*.example.com/*

Ограничение API

Разрешено:

Maps JavaScript API

Запрещено:

Geocoding API
Directions API
Distance Matrix API
Roads API

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

---

Рекомендации по безопасности

Использование отдельных ключей

Для каждого окружения желательно создавать собственный ключ:

• Development;
• Testing;
• Staging;
• Production.

Это позволяет быстро отзывать доступ и отслеживать использование.

---

Минимизация разрешений

Следует предоставлять только те права, которые действительно необходимы.

Нежелательно использовать настройки:

None

или

Don't restrict key

Даже временно такие конфигурации могут привести к несанкционированному использованию.

---

Регулярный аудит

Необходимо периодически проверять:

• список разрешенных доменов;
• список разрешенных IP;
• набор доступных API;
• статистику использования ключей;
• журнал ошибок авторизации.

Подобный аудит помогает своевременно обнаруживать утечки и ошибки конфигурации.

---

Разделение клиентских и серверных ключей

Наиболее безопасной считается схема:

Назначение	Тип ограничения
Google Maps JavaScript API	Домен
Geocoding API на сервере	IP
Places API на сервере	IP
Внутренние сервисы	IP

Разделение ключей снижает последствия компрометации одного из компонентов системы.

---

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

При возникновении ошибок рекомендуется проверить:

1. Правильность API-ключа.
2. Наличие разрешенного домена.
3. Совпадение протокола HTTP/HTTPS.
4. Наличие нужного поддомена.
5. Активирован ли Maps JavaScript API в проекте.
6. Корректность ограничений API.
7. Отсутствие ограничений IP для браузерного ключа.
8. Статус биллинга Google Cloud.
9. Логи использования ключа в Google Cloud Console.

Последовательная проверка этих пунктов позволяет устранить большинство проблем, связанных с ограничениями API-ключей Google Maps JavaScript API.