MapLibre GL JS изначально проектировалась как библиотека, не
завязанная на обязательную модель API-ключей, в отличие от некоторых
коммерческих картографических стеков. Это ключевое архитектурное отличие
влияет на подход к безопасности: основная угроза возникает не на уровне
самой библиотеки, а на уровне источников тайлов, стилей и сторонних API,
которые используются вместе с ней.
API-ключи в экосистеме картографии чаще всего относятся к следующим
компонентам:
- серверы тайлов (raster/vector tiles)
- сервисы геокодирования и маршрутизации
- CDN для стилей и шрифтов
- аналитические и телеметрические API
MapLibre GL JS выступает клиентом, а значит любая утечка ключа
происходит не из библиотеки, а из приложения, которое её использует.
Типы ключей в
картографических приложениях
Публичные ключи доступа
Публичные ключи применяются для:
- доступа к тайлам с ограничениями по домену
- загрузки стилей (style.json)
- подключения к геокодерам
Характерная особенность: такие ключи не должны быть
секретом, но обязаны иметь ограничения:
- доменные ограничения (allowed origins)
- лимиты запросов
- ограничение по сервисам
Даже публичный ключ становится опасным при отсутствии
ограничений.
Секретные ключи (server-side)
Используются для:
- генерации временных токенов
- подписания URL (signed URLs)
- доступа к приватным данным (enterprise tile sets)
Такие ключи:
- никогда не передаются в браузер
- используются только на сервере
- часто имеют короткий TTL (time-to-live)
Временные токены (JWT /
signed tokens)
Наиболее безопасная практика — выдача клиенту временного токена:
- создаётся на сервере
- содержит scope (tile:read, geocode:read)
- имеет срок жизни (например, 10–60 минут)
- может быть привязан к IP или session id
Уязвимости при работе с
API-ключами
Попадание ключа в клиентский
код
Основные источники утечек:
- захардкоженные строки в JavaScript
- переменные окружения, попавшие в bundle (Vite, Webpack)
- публичные репозитории
- source maps в продакшене
Важно учитывать: любой ключ в браузере считается публичным по
определению.
Даже при использовании сборщиков:
- ключи видны в Network tab
- можно извлечь style URL
- можно восстановить tile endpoints
Поэтому защита не строится на сокрытии, а только на ограничении прав
доступа.
Подмена style.json
Файл стиля может содержать:
- URL тайл-сервера
- ссылки на шрифты
- источники данных
При отсутствии контроля:
- можно подменить стиль через XSS или CDN-атаку
- получить доступ к внутренним слоям данных
Безопасная
архитектура использования API-ключей
Принцип минимальных
привилегий
Каждый ключ должен иметь только необходимый доступ:
- только чтение тайлов
- только определённые слои
- только конкретные домены
Избыточные права увеличивают радиус атаки.
Ограничение по доменам
На стороне провайдера API обязательно задаются:
- allowed origins:
https://example.com
- запрет wildcard
* в продакшене
- отдельные ключи для dev/staging/prod
Это базовый уровень защиты публичных ключей.
Использование backend proxy
Одна из наиболее устойчивых архитектур:
- браузер → backend → tile server
- ключ хранится только на сервере
- клиент не знает реальный endpoint
Преимущества:
- скрытие API-ключа
- возможность кеширования
- централизованный контроль запросов
- защита от злоупотреблений
Недостатки:
- увеличение задержек
- нагрузка на backend
Хранение ключей в
frontend-проектах
Переменные окружения
В современных сборщиках:
.env используется для конфигурации- переменные с префиксом
PUBLIC_ попадают в клиент
Ошибка: считать .env безопасным хранилищем.
Любая переменная, попавшая в bundle:
- становится доступной пользователю
- может быть извлечена из JS-файлов
Разделение конфигураций
Практика разделения:
- frontend config (публичные URL)
- backend config (секретные ключи)
- runtime config (загружается динамически)
Особенно важно при использовании CDN.
Защита tile endpoints
Подписанные URL
Пример механизма:
- сервер генерирует URL с подписью
- подпись содержит hash + expiry
- сервер проверяет валидность
Используется для:
- приватных векторных тайлов
- корпоративных картографических данных
Rate limiting
Даже при утечке ключа защита может включать:
- ограничение запросов в секунду
- лимит на пользователя
- throttling по IP
Это снижает ущерб от злоупотребления.
Кеширование
Кеширование уменьшает:
- количество запросов к API
- стоимость использования платных сервисов
- вероятность превышения лимитов
Используются:
- CDN caching
- browser cache headers
- service worker caching
MapLibre GL JS
и отсутствие обязательных ключей
Одно из ключевых архитектурных преимуществ заключается в том, что
MapLibre GL JS не требует встроенной системы API-ключей. Это
означает:
- библиотека не блокирует доступ к рендерингу
- можно использовать собственные tile servers
- возможно полностью offline-развёртывание
- контроль над инфраструктурой остаётся у разработчика
Ключи появляются только как часть внешних сервисов, а не самой
библиотеки.
Типовые модели интеграции с
ключами
Модель прямого доступа
- ключ хранится в frontend
- запросы идут напрямую к API
Применяется только для:
- публичных демо
- ограниченных бесплатных планов
Модель через gateway
- frontend → backend API → tile provider
- ключ скрыт
- backend выполняет аутентификацию
Модель self-hosted tiles
- собственный tile server
- отсутствие внешних API-ключей
- доступ регулируется внутренней сетью
Контроль доступа на уровне
стилей
Style JSON является критическим объектом:
- содержит источники данных
- определяет слои карты
- задаёт шрифты и sprites
Методы защиты:
- хранение стилей на приватном CDN
- подпись URL стиля
- динамическая выдача через backend
- разделение стилей по ролям пользователей
Практика ротации ключей
Регулярная ротация снижает риск компрометации:
- создание нового ключа
- обновление конфигурации
- отзыв старого ключа
- мониторинг ошибок 401/403
Автоматизация:
- CI/CD pipeline обновляет ключи
- secrets manager (Vault, AWS Secrets Manager)
- environment-based deployment
Логирование и
мониторинг использования ключей
Контроль включает:
- аномальные всплески запросов
- географически невозможные обращения
- превышение квот
- несанкционированные домены
Логи помогают:
- выявлять утечки
- блокировать злоупотребления
- оптимизировать лимиты
Ошибки
проектирования, приводящие к утечкам
- использование одного ключа для всех окружений
- отсутствие доменных ограничений
- хранение ключа в Git-репозитории
- публикация source maps без фильтрации
- прямой доступ к backend API без auth
Модель доверия в
картографических приложениях
Безопасность API-ключей в MapLibre-экосистеме строится на
принципе:
- клиенту нельзя доверять
- ключи не являются секретом, если они в браузере
- безопасность достигается архитектурой, а не сокрытием
Эта модель особенно важна при использовании MapLibre GL JS в
масштабных веб-приложениях с большим количеством пользователей и внешних
интеграций.