Token аутентификация

В экосистеме Cesium доступ к облачным ресурсам платформы Cesium осуществляется через систему токенов доступа. Основной механизм предназначен для идентификации клиента при запросах к Cesium ion, загрузке 3D Tiles, террейна, изображений и других геопространственных данных. Токен выступает обязательным элементом авторизации при работе с облачными сервисами и определяет уровень доступа к ресурсам аккаунта.

Назначение access token в Cesium ion

Access token в Cesium ion выполняет роль ключа API, который связывает запросы приложения с конкретным аккаунтом. Без корректного токена:

  • невозможна загрузка террейна Cesium World Terrain
  • недоступны стили и слои из Cesium ion Assets
  • блокируются запросы к защищённым 3D Tiles
  • ограничивается доступ к приватным ресурсам пользователя

Токен не просто идентифицирует приложение, но и определяет разрешённые операции: чтение ассетов, использование публичных наборов данных, доступ к платным слоям.

Основной способ подключения токена

В CesiumJS токен устанавливается глобально через объект Cesium.Ion. Это влияет на все последующие запросы к Cesium ion.

import { Ion } from "cesium";

Ion.defaultAccessToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6...";

После установки:

  • все запросы к Cesium ion автоматически подписываются токеном
  • нет необходимости передавать токен в каждый запрос отдельно
  • инициализация должна происходить до создания Viewer

Использование токена в Viewer

При создании сцены Viewer токен уже должен быть установлен глобально, иначе часть ресурсов не загрузится.

import { Viewer, Ion, createWorldTerrain } from "cesium";

Ion.defaultAccessToken = "TOKEN";

const viewer = new Viewer("cesiumContainer", {
  terrainProvider: createWorldTerrain()
});

В данном сценарии:

  • terrainProvider обращается к Cesium World Terrain
  • токен используется автоматически
  • при отсутствии токена происходит ошибка авторизации

Типы токенов и их назначение

В системе Cesium ion существует несколько категорий токенов:

Полный access token

Используется для разработки и серверной интеграции. Даёт доступ ко всем ресурсам аккаунта.

Ограниченный token (scoped token)

Позволяет ограничить:

  • доступ к конкретным assets
  • операции только на чтение
  • использование в публичных приложениях

Временный token

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

  • используется в безопасных архитектурах
  • позволяет не хранить главный ключ в клиенте
  • часто применяется в production

Архитектура безопасного хранения токена

Хранение токена напрямую в клиентском JavaScript считается потенциально небезопасным, поскольку:

  • токен виден в исходном коде
  • может быть извлечён из браузера
  • может быть использован сторонними лицами

Поэтому распространённая архитектура включает серверный слой:

  1. клиент запрашивает временный токен
  2. сервер проверяет пользователя
  3. сервер выдаёт scoped token
  4. клиент использует токен только в памяти

Использование переменных окружения

В сборках на базе Vite, Webpack или Node.js токен часто передаётся через переменные окружения:

const token = process.env.CESIUM_ION_TOKEN;

Ion.defaultAccessToken = token;

Такой подход:

  • исключает захардкоженные ключи
  • упрощает переключение окружений (dev / prod)
  • снижает риск утечки при публикации репозитория

Обновление и ротация токенов

Токены Cesium ion могут быть отозваны или обновлены. В таких случаях необходимо:

  • перезаписать Ion.defaultAccessToken
  • пересоздать Viewer при необходимости
  • перезагрузить источники данных, если они зависят от авторизации

Динамическая замена токена:

Ion.defaultAccessToken = "NEW_TOKEN";
viewer.scene.requestRender();

Однако часть ресурсов может потребовать повторной инициализации провайдеров.

Токен и загрузка 3D Tiles

При работе с 3D Tiles токен передаётся автоматически через Ion API.

import { Cesium3DTileset, IonResource } from "cesium";

const tileset = new Cesium3DTileset({
  url: IonResource.fromAssetId(12345)
});

Здесь происходит цепочка:

  • assetId связывается с ресурсом Cesium ion
  • токен добавляется в HTTP-запрос
  • сервер возвращает тайлы при успешной авторизации

Использование токена без глобальной установки

В некоторых сценариях токен передаётся явно через ресурсы:

const resource = IonResource.fromAssetId(12345, {
  accessToken: "TOKEN"
});

Такой подход используется:

  • при мультиаккаунтных системах
  • при проксировании запросов
  • в изолированных модулях загрузки данных

Ошибки аутентификации

При некорректной настройке токена возникают типовые ошибки:

  • 401 Unauthorized — отсутствует или недействителен токен
  • 403 Forbidden — нет доступа к ресурсу
  • Invalid access token — повреждён формат токена
  • Asset not found — отсутствуют права на assetId

Диагностика обычно сводится к проверке:

  • корректности строки токена
  • актуальности ключа
  • соответствия прав доступа

Работа в серверной среде (Node.js)

CesiumJS может использоваться на сервере для подготовки данных. В этом случае токен передаётся так же:

import { Ion } from "cesium";

Ion.defaultAccessToken = process.env.CESIUM_TOKEN;

Особенности серверной среды:

  • отсутствует браузерный кеш авторизации
  • запросы выполняются напрямую через HTTP
  • необходимо учитывать rate limits Cesium ion

Политика безопасности и ограничения токенов

Токены Cesium ion поддерживают ограничения:

  • по доменам (referrer restrictions)
  • по типу операций (read-only / write)
  • по конкретным asset ID
  • по времени жизни

Рекомендуемая практика — минимизация прав токена:

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

Влияние токена на производительность и кэширование

Сам токен не влияет напрямую на рендеринг сцены, но влияет на:

  • доступ к CDN Cesium ion
  • кэширование ответов API
  • повторное использование ресурсов

Запросы с одинаковым токеном и assetId могут кешироваться на уровне браузера и CDN, ускоряя загрузку сцены при повторных обращениях.

Интеграция с прокси-серверами

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

  • клиент обращается к внутреннему API
  • сервер добавляет токен к запросам Cesium ion
  • результат возвращается клиенту без раскрытия ключа

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

app.get("/terrain", async (req, res) => {
  const url = buildCesiumUrl(req.query.assetId);
  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.CESIUM_TOKEN}`
    }
  });
  res.send(await response.arrayBuffer());
});

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

Если токен не установлен:

  • базовые функции Viewer могут работать частично
  • глобус Cesium World Terrain не загружается
  • большинство ion-ресурсов становятся недоступными
  • консоль браузера фиксирует ошибки авторизации

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

Оглавление