Рефереры и CORS

В веб-платформах геосервисов, включая HERE Technologies, механизм контроля доступа к API часто опирается на HTTP-заголовок Referer. Он передаётся браузером автоматически при загрузке ресурсов и позволяет серверу определить, с какого домена инициирован запрос.

Ограничение доступа по доменам

При использовании JavaScript SDK карт ключ API (API Key) привязывается не только к самому ключу, но и к набору разрешённых источников запросов. Это формирует слой защиты, предотвращающий:

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

Проверка выполняется на стороне серверов HERE: каждый запрос анализируется по полю Referer и сопоставляется с белым списком доменов, заданных в консоли разработчика.

Пример типичного ограничения:

  • https://example.com/*
  • https://maps.example.com/*
  • http://localhost:* (для разработки)

Если домен отсутствует в списке, запрос к тайлам, геокодингу или JS-API отклоняется с ошибкой авторизации.

Особенности поведения Referer

HTTP Referer не является абсолютно надёжным источником идентификации:

  • может быть обрезан политиками браузера (Referrer-Policy);
  • отсутствует при некоторых типах запросов (например, при переходах с HTTPS на HTTP при строгих настройках);
  • не передаётся при прямых серверных запросах (Node.js, backend).

Поэтому в современных архитектурах Referer используется только как дополнительный слой защиты, а не как единственный механизм контроля доступа.

CORS в HERE Maps API

Механизм Cross-Origin Resource Sharing (CORS) определяет, каким образом браузер выполняет запросы между разными доменами.

В случае HERE Maps API CORS критически важен, поскольку:

  • карты и тайлы загружаются с CDN-доменов HERE;
  • JavaScript-приложение почти всегда работает на другом домене;
  • API-запросы (геокодинг, маршрутизация) выполняются из браузера.

Основной принцип CORS

Браузер по умолчанию запрещает запросы к чужим доменам. CORS вводит механизм явного разрешения через HTTP-заголовки:

  • Access-Control-Allow-Origin
  • Access-Control-Allow-Methods
  • Access-Control-Allow-Headers

Сервер HERE отвечает с корректными заголовками, разрешающими доступ доверенным источникам.

Префлайт-запрос (OPTIONS)

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

  • использовании кастомных заголовков;
  • POST-запросах к API;
  • отправке JSON-данных.

Схема работы:

  1. Браузер отправляет OPTIONS на сервер HERE.
  2. Сервер отвечает, разрешены ли методы и заголовки.
  3. Только после этого выполняется основной запрос.

Пример HTTP-обмена:

OPTIONS /v1/geocode HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: GET

Ответ сервера:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Authorization

Взаимодействие Referer и CORS

Referer и CORS решают разные задачи, но в HERE Maps API они работают совместно:

Механизм Уровень Назначение
Referer серверный контроль проверка допустимого домена
CORS браузерный контроль разрешение cross-origin запросов

Важно, что:

  • Referer проверяется на стороне HERE как часть политики API key;
  • CORS контролируется HTTP-ответами сервера;
  • даже при корректном CORS запрос может быть отклонён из-за неверного Referer.

API Key и ограничения источников

При создании ключа доступа в панели разработчика HERE Developer Portal задаются ограничения:

  • список доменов (Referer restrictions);
  • разрешённые API (Geocoding, Routing, Maps JS);
  • лимиты запросов.

Пример логики проверки:

  1. Запрос приходит с https://site.com/app.
  2. Сервер извлекает Referer.
  3. Проверяет совпадение с шаблоном.
  4. Если совпадает — выполняется проверка API key.
  5. Затем применяется CORS-политика.

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

1. CORS error в консоли браузера

Причины:

  • сервер не возвращает Access-Control-Allow-Origin;
  • запрос идёт на неподдерживаемый endpoint;
  • используется неправильный метод (например, POST вместо GET).

2. Invalid referer / Unauthorized

Причины:

  • домен не добавлен в список разрешённых;
  • используется localhost без явного разрешения;
  • несоответствие протокола (http vs https).

3. Preflight failed

Причины:

  • сервер не поддерживает OPTIONS;
  • отсутствуют нужные заголовки;
  • блокировка корпоративным прокси.

Особенности работы HERE Maps JavaScript SDK

При подключении SDK:

<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>

происходит несколько уровней запросов:

  1. Загрузка библиотек JS (CDN HERE).
  2. Запрос тайлов карты (Tile API).
  3. Дополнительные запросы к сервисам (Search, Routing).

Каждый из них проходит:

  • проверку API key;
  • проверку Referer;
  • CORS-проверку.

Безопасность и архитектурные ограничения

Использование Referer и CORS в связке формирует многоуровневую модель защиты:

  • предотвращение кражи API key;
  • ограничение использования SDK вне разрешённых доменов;
  • защита от прямых cross-origin вызовов.

Однако архитектура не предполагает:

  • полной секретности ключа в браузере;
  • использования API key как серверного токена;
  • доверия к клиентскому коду.

Для серверных интеграций применяется отдельный контур авторизации, где CORS отсутствует как ограничение, а контроль осуществляется через ключи доступа и токены.

Поведение в локальной разработке

При работе на localhost возникают особенности:

  • необходимо явно добавлять http://localhost:PORT в список разрешённых доменов;
  • иногда требуется разрешение 127.0.0.1;
  • HTTPS и HTTP считаются разными origin.

Пример корректной конфигурации:

  • http://localhost:3000
  • http://127.0.0.1:5500

Прокси как обходной слой CORS

В некоторых архитектурах используется сервер-прокси:

Browser → Own Backend → HERE API

В этом случае:

  • браузер обращается к своему серверу (CORS отсутствует);
  • сервер выполняет запрос к HERE API;
  • Referer может отсутствовать или заменяться серверной логикой.

Такой подход применяется при:

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

Итоговая модель взаимодействия

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

  1. API key валиден.
  2. Referer соответствует разрешённому домену.
  3. CORS разрешает cross-origin доступ.
  4. Пройдены ограничения квот и тарифов.

Эта многослойная система обеспечивает баланс между удобством использования JavaScript SDK и контролем доступа к геопространственным данным, предоставляемым HERE Technologies.

Оглавление