Ограничение доменов

Ограничение доступа к ключам и разрешение использования API только с доверенных доменов является базовым механизмом защиты в экосистеме HERE Technologies. В JavaScript-библиотеке HERE Maps API for JavaScript эта концепция реализуется через контроль источников запросов (referrer restriction) и настройку разрешённых доменов для ключей доступа.

Любой клиентский JavaScript-код выполняется в открытой среде браузера, что делает API-ключи потенциально уязвимыми. Если ключ попадает в чужие руки, он может быть использован для генерации запросов, влияющих на квоты, биллинг и стабильность сервиса.

Ограничение доменов решает задачу привязки ключа к конкретным источникам запросов. Браузер автоматически передаёт заголовок Referer, который содержит адрес страницы, инициировавшей запрос. Платформа сравнивает этот адрес с заранее заданным списком разрешённых доменов.

Модель безопасности referrer-based ограничения

В основе механизма лежит проверка HTTP-заголовка:

запрос отправляется из браузера;
система извлекает домен из Referer;
выполняется сопоставление с белым списком;
при совпадении запрос обрабатывается, иначе отклоняется.

Такой подход позволяет:

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

Настройка ограничений в HERE Developer Portal

В экосистеме HERE доступ к API-ключам управляется через консоль разработчика. Для каждого ключа задаются параметры безопасности, включая список разрешённых источников.

Типичная конфигурация включает:

домены верхнего уровня (например, example.com);
поддомены (app.example.com, maps.example.com);
локальные адреса для разработки (localhost, 127.0.0.1).

Пример логики допустимых значений:

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

Такой подход позволяет гибко разделять среды:

production-домен;
staging-среда;
локальная разработка.

Поведение API при нарушении ограничений

При несоответствии домена запрос блокируется на уровне сервера HERE. В ответ возвращается ошибка авторизации, чаще всего связанная с:

недействительным ключом;
запрещённым источником;
нарушением политики использования.

На стороне клиента это проявляется как:

отсутствие тайлов карты;
ошибки загрузки слоёв;
сбои геокодирования или маршрутизации.

Ограничение доменов и API key vs App ID

В современных конфигурациях HERE используются API keys, однако в более старых реализациях применялись App ID и App Code.

Различие в контексте ограничения доменов:

App ID/App Code: ограничения задавались через referrer whitelist;
API Key: контроль осуществляется через более гибкие политики доступа, включая домены и IP (для серверных сценариев).

Несмотря на эволюцию системы, принцип остаётся одинаковым: ключ должен быть привязан к конкретному источнику использования.

Пример конфигурации ограничения доменов

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

разрешённый домен: https://maps.example.com
разрешённые поддомены: https://*.example.com
локальная разработка: http://localhost:3000

В результате ключ будет работать только при выполнении условий:

запрос инициирован с разрешённого origin;
отсутствует подмена referrer;
протокол соответствует заданному (http/https).

Ограничения и особенности работы в браузере

Механизм referrer-based фильтрации имеет ряд технических особенностей:

1. Возможность отсутствия Referer

Некоторые браузеры или настройки приватности могут:

обрезать referrer;
передавать только домен без пути;
полностью удалять заголовок.

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

2. HTTPS и HTTP как разные источники

Система рассматривает:

https://example.com
http://example.com

как разные origin. Это важно при настройке разрешений.

3. Поддомены и wildcard

Использование *.example.com позволяет охватывать:

user.example.com;
dev.example.com;
api.example.com.

Но не включает:

example.com (корневой домен, если не указан отдельно).

Серверная прокси-архитектура и обход ограничений

В архитектурах, где используется backend-прокси, ограничение доменов может работать иначе:

браузер отправляет запрос на собственный сервер;
сервер обращается к HERE API напрямую;
ключ хранится на сервере и не зависит от referrer.

В таком случае доменные ограничения:

либо отключаются;
либо заменяются IP-ограничениями;
либо комбинируются с токенами доступа.

Практика разделения ключей по средам

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

ключ для production-домена;
ключ для тестовой среды;
отдельный ключ для локальной разработки.

Каждый ключ имеет собственный whitelist, что позволяет:

отслеживать источники трафика;
изолировать окружения;
предотвращать утечки между средами.

Типичные ошибки при настройке доменов

Некорректный протокол

Добавление только example.com без https:// может привести к несрабатыванию проверки.

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

Если приложение доступно на app.example.com, но разрешён только example.com, запросы будут блокироваться.

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

Локальные среды часто используют разные порты:

localhost:3000
localhost:5173

Если порт не учтён, доступ будет запрещён.

Поведение при CDN и reverse proxy

При использовании CDN или прокси-инфраструктуры:

реальный origin может отличаться от внешнего домена;
referrer может быть модифицирован;
требуется согласованная настройка CORS и whitelist.

В таких системах важно учитывать цепочку:

браузер → CDN → origin server → HERE API.

Влияние ограничения доменов на производительность

Сам механизм проверки не влияет на клиентскую производительность, однако неправильная настройка может приводить к:

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

Совместимость с другими механизмами безопасности

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

rate limiting;
IP filtering (для серверных API);
подписанными токенами;
временными ключами доступа.

Комбинация этих механизмов формирует многоуровневую модель защиты, где домен является первой линией проверки в браузерных сценариях.