В Mapbox GL JS контроль доступа к картам и тайлам часто строится
вокруг access token, который может быть ограничен по
доменам через механизм referrer restrictions. В браузерной среде каждый
запрос к API Mapbox сопровождается заголовком Referer,
который содержит адрес страницы, инициировавшей запрос. Именно этот
заголовок используется серверной стороной Mapbox для проверки, разрешён
ли данный источник.
Referrer restrictions выступают дополнительным уровнем безопасности поверх токена, предотвращая его использование вне доверенных доменов.
Заголовок Referer формируется браузером автоматически
при выполнении сетевых запросов. В контексте Mapbox GL JS он включается
в:
/styles/v1/...)/v4/...)Значение Referer обычно содержит:
https://)Пример:
Referer: https://example.com/maps/index.htmlИменно доменная часть используется для сопоставления с правилами ограничения доступа.
При включённых ограничениях на access token сервер Mapbox выполняет последовательную проверку:
Referer из HTTP-запросаЕсли Referer отсутствует, запрос чаще всего считается
небезопасным и блокируется.
Access token в Mapbox может быть ограничен списком разрешённых источников. В конфигурации обычно задаются:
example.com)*.example.com)localhost)127.0.0.1)Пример логики:
https://example.com → разрешеноhttps://app.example.com → разрешено при wildcardhttps://evil-site.com → отклоненоWildcard работает только на уровне поддоменов и не распространяется на произвольные строки.
Если запрос выполняется с неподходящего origin, библиотека Mapbox GL JS возвращает ошибки на уровне загрузки ресурсов:
Типичные сообщения:
401 UnauthorizedNot Authorized - Invalid TokenThis request requires a token with URL restrictionsВ результате карта может отображаться пустой или частично загруженной.
Access token в Mapbox является ключевым идентификатором проекта. Referrer restrictions не заменяют его, а дополняют.
Комбинация работает следующим образом:
Даже при валидном токене запрос будет отклонён, если домен не входит в список разрешённых.
Локальная разработка требует отдельной настройки, поскольку
Referer в этом случае отличается от продакшн-домена.
Часто используются:
http://localhost:3000http://127.0.0.1:5500http://localhost:* (частичная поддержка через
wildcard)Некоторые ограничения:
localhost и 127.0.0.1 не эквивалентныОтсутствие корректной настройки приводит к тому, что карта работает в одной среде и перестаёт работать в другой.
Современные браузеры позволяют контролировать поведение заголовка
Referer через HTTP заголовок
Referrer-Policy.
Примеры значений:
no-referrer — полностью отключает отправкуorigin — отправляет только домен без путиstrict-origin-when-cross-origin — ограничивает данные
при переходах между доменамиДля Mapbox GL JS критично, чтобы хотя бы origin присутствовал. Полное отключение referrer приводит к отказу в авторизации запросов.
Хотя CSP напрямую не управляет referrer restrictions, он влияет на загрузку ресурсов Mapbox:
connect-src могут блокировать
API-запросыimg-src влияет на растровые тайлыworker-src важен для WebGL worker-овПри неправильной CSP конфигурации запросы могут блокироваться ещё до стадии проверки referrer.
При серверных запросах (например, SSR или backend-геокодинг)
заголовок Referer обычно отсутствует.
В таких случаях Mapbox применяет альтернативные механизмы:
Для Mapbox GL JS в браузере отсутствие referrer почти всегда означает невозможность использовать токен с доменными ограничениями.
Wildcard-правила позволяют расширять список допустимых источников:
*.example.com покрывает поддоменыexample.org)http vs
https)Также wildcard не применяется к путям:
Частые проблемы при работе с referrer restrictions:
localhost без портаhttps вместо http127.0.0.1 в списке разрешённыхno-referrer в браузере или meta-тегахПри диагностике проблем обычно анализируются:
Referer в DevTools → NetworkКлючевой шаг — сравнение ожидаемого и реального значения origin.
Referrer-based ограничения используются как слой защиты от:
Несмотря на то, что referrer можно подделать в не-браузерных средах, в контексте веб-клиента он остаётся эффективным механизмом контроля происхождения запросов.
При использовании CDN или reverse proxy возможны искажения referrer:
RefererВ таких случаях Mapbox видит не внешний сайт, а промежуточный сервер, что приводит к блокировке запросов при несоответствии whitelist.
Если приложение работает по HTTPS, а запросы к Mapbox происходят через HTTP (или наоборот), referrer может:
Это приводит к ошибкам авторизации даже при корректной настройке домена.
Упрощённая логика проверки выглядит следующим образом:
Любое несоответствие на шаге 3 приводит к отказу независимо от остальных условий.