Управление доступом

Mapbox GL JS использует модель доступа, основанную на токенах, где ключевым механизмом контроля выступает access token, определяющий уровень разрешений к API, стилям, тайлам и дополнительным сервисам платформы Mapbox. Архитектура доступа построена вокруг обязательной аутентификации каждого запроса к векторным тайлам, растровым тайлам и стилям карты.

Типы access token и их роль

Public token

  • Используется на стороне клиента (браузер, мобильные WebView)
  • Предназначен для публичных приложений
  • Ограничивается доменами, URL-ами или scope
  • Применяется в большинстве сценариев отображения карт

Secret token

  • Используется на серверной стороне
  • Позволяет создавать, обновлять и управлять ресурсами аккаунта
  • Не должен попадать в клиентский код

Scoped token

  • Ограниченный набор разрешений
  • Позволяет минимизировать риск компрометации
  • Используется для разделения доступа между средами (dev/staging/prod)

Установка токена в Mapbox GL JS

Основной механизм инициализации доступа:

mapboxgl.accessToken = 'pk.XXXXXXXXXXXXXXXXXXXXXXXX';

или динамическая установка:

import mapboxgl from 'mapbox-gl';

mapboxgl.accessToken = process.env.MAPBOX_TOKEN;

Ключ accessToken применяется ко всем запросам, которые выполняет рендерер: стили, источники данных, тайлы, geocoding API (при использовании дополнительных модулей).

Модель аутентификации запросов

Каждый сетевой запрос к API Mapbox автоматически получает токен:

  • /styles/v1/...
  • /tilesets/v1/...
  • /v4/{tileset}
  • /v5/{endpoint}

Токен передаётся как query parameter:

?access_token=pk.xxx

Это означает, что контроль доступа реализуется на уровне HTTP-запросов, а не внутри клиента.

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

При создании токена задаются URL restrictions, которые ограничивают использование:

  • по домену (example.com)
  • по поддоменам (*.example.com)
  • по протоколу (HTTPS-only)

Поведение при несоответствии:

  • запрос возвращает 401 Unauthorized
  • карта не загружается или остаётся пустой
  • в консоли появляются ошибки загрузки ресурсов

Обработка ошибок доступа

Типичные сценарии отказа:

401 Unauthorized

  • неверный токен
  • истёкший токен
  • домен не входит в allowlist

403 Forbidden

  • отсутствие прав scope
  • доступ к закрытому tileset

Обработка на уровне Mapbox GL JS:

map.on('error', (e) => {
  if (e.error && e.error.status === 401) {
    console.error('Access token invalid or unauthorized');
  }
});

Динамическое управление токеном

В runtime токен может быть изменён:

mapboxgl.accessToken = newToken;

Однако уже загруженные источники не пересчитываются автоматически; требуется пересоздание карты:

map.remove();
map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11'
});

Безопасное хранение токенов

На клиенте token неизбежно доступен, поэтому защита строится не на скрытии, а на ограничении:

  • environment variables в build-time
  • server-side injection через HTML template
  • использование CI/CD secret storage

Пример через bundler:

accessToken: import.meta.env.VITE_MAPBOX_TOKEN

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

Дополнительный уровень контроля реализуется через перехват запросов:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11',
  transformRequest: (url, resourceType) => {
    return {
      url,
      headers: resourceType === 'Source'
        ? { 'X-Custom-Header': 'value' }
        : {}
    };
  }
});

Применение:

  • добавление собственных auth headers
  • проксирование запросов через backend
  • логирование всех сетевых обращений

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

Архитектура проксирования позволяет исключить прямой доступ клиента к API:

Browser → Backend → Mapbox API

Преимущества:

  • скрытие token от клиента
  • централизованный контроль доступа
  • кэширование тайлов
  • rate limiting

Пример backend proxy:

app.get('/tiles/:z/:x/:y', async (req, res) => {
  const url = `https://api.mapbox.com/v4/.../${req.params.z}/${req.params.x}/${req.params.y}.mvt?access_token=${TOKEN}`;

  const response = await fetch(url);
  response.body.pipe(res);
});

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

Map styles также защищены токеном:

style: 'mapbox://styles/username/styleid'

Без корректного токена:

  • стиль не загружается
  • отображается пустой canvas
  • генерируется ошибка загрузки ресурсов

Контроль доступа к tilesets

Tilesets имеют собственные permissions:

  • public tilesets
  • private tilesets
  • organization-restricted datasets

Пример обращения:

mapbox://tileset-id

Проверка доступа происходит на уровне сервера Mapbox до отдачи данных.

Изоляция окружений (dev / staging / prod)

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

  • dev token: без ограничений домена
  • staging token: ограниченный список URL
  • production token: строгие restrictions + минимальные scopes

Это снижает риск утечки полномочий между окружениями.

Отзыв и ротация токенов

Управление жизненным циклом токенов включает:

  • manual revoke через dashboard
  • автоматическую ротацию
  • выпуск нового token + деплой приложения
  • деактивацию старого после миграции

При отзыве токена все активные клиенты теряют доступ к API моментально.

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

При invalid token:

  • стиль перестаёт обновляться
  • источники данных возвращают ошибки
  • тайлы не загружаются при панорамировании
  • zoom transitions могут зависать на частично загруженных данных

Cross-Origin и доступ к ресурсам

Mapbox API использует CORS-заголовки:

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

В случае проксирования требуется корректная настройка CORS на стороне backend, иначе WebGL canvas блокирует загрузку ресурсов.

Безопасность WebGL слоя

В контексте Mapbox GL JS важно учитывать:

  • данные тайлов рендерятся через WebGL
  • утечка данных возможна через canvas export (toDataURL)
  • приватные данные не должны попадать в клиентские источники без фильтрации

Политика минимальных прав

Рекомендуемая модель доступа:

  • отдельные token для каждого приложения
  • минимально необходимый scope
  • ограничения по URL
  • запрет secret token в браузере
  • отдельные token для аналитики и картографии

Интеграция с OAuth и внешними системами

Mapbox token не заменяет OAuth, но может использоваться вместе с ним:

  • OAuth контролирует пользователя
  • Mapbox token контролирует доступ к картографическим ресурсам
  • backend связывает оба уровня авторизации

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

На уровне аккаунта фиксируются:

  • количество запросов
  • типы API вызовов
  • источники трафика
  • ошибки авторизации

Это позволяет выявлять:

  • утечки token
  • аномальные запросы
  • превышение лимитов
Оглавление