acdn.uz ACDN - Документация
Войти
EN / RU
Документация

Токен-аутентификация

Детальная генерация токена и причины 403.

Токен-аутентификация

Когда функция включена, запрос должен содержать валидный токен и timestamp истечения. Невалидные или истекшие подписи отклоняются с 403.

  • Основной параметр токена: acdn_token (legacy token также поддерживается).
  • Обязательный параметр истечения: expires (Unix timestamp).
  • Опциональный параметр области действия: token_path.
  • Опциональная привязка к IP включает source IP клиента в payload подписи.
  • Поддерживаются query-token и path-token форматы URL.

Процесс генерации токена

ACDN использует модель подписанных URL с параметрами формата ACDN и режимами совместимости.

  1. Нормализуйте путь запроса и выберите signed path: token_path (если задан) или исходный путь.
  2. Соберите query-параметры и исключите auth-поля: token, acdn_token и expires.
  3. Отсортируйте ключи параметров лексикографически и сериализуйте как key=value через ampersand.
  4. Соберите hashable-строку: token_key + signed_path + expires.
  5. Если на зоне включен token_ip, добавьте IP клиента в hashable-строку.
  6. Добавьте сериализованные параметры и вычислите SHA-256 с base64url-выводом без padding.
  7. Передайте токен в acdn_token, а срок истечения в expires.

Краткий алгоритм:

hashable = token_key + signed_path + expires
if token_ip_enabled:
  hashable += client_ip
hashable += canonical_query_without(acdn_token, token, expires)
token = base64url(sha256(hashable))

Параметры токена и область действия

acdn_token

Обязательный

Основной параметр токена. В query-режиме также принимается legacy token.

expires

Обязательный

Unix timestamp в секундах. После этого времени запрос отклоняется.

token_path

Опциональный

Ограничивает токен указанным префиксом пути. Запрос должен попадать в этот scope.

token_ip

Опционально (настройка зоны)

Если включено на зоне, IP клиента становится частью подписи.

Форматы подписанных URL

Формат query-токена:

https://cdn.example.uz/video/intro.mp4?acdn_token=TOKEN_VALUE&expires=1767225600

Формат path-токена:

https://cdn.example.uz/acdn_token=TOKEN_VALUE&expires=1767225600/video/intro.mp4

Токен со scope через token_path:

https://cdn.example.uz/video/intro.mp4?quality=hd&acdn_token=TOKEN_VALUE&expires=1767225600&token_path=/video

PHP-пример, согласованный с ACDN signer:

$params = ['quality' => 'hd', 'token_path' => '/video'];
$expires = time() + 3600;
ksort($params, SORT_STRING);

$hashParts = [];
foreach ($params as $key => $value) {
    $hashParts[] = $key . '=' . (string) $value;
}

$hashable = $tokenKey . '/video' . $expires . implode('&', $hashParts);
$token = rtrim(strtr(base64_encode(hash('sha256', $hashable, true)), '+/', '-_'), '=');

Частые причины 403

  • Рассинхрон времени или устаревший expires.
  • Подписанный путь не совпадает с путем запроса или scope token_path.
  • Параметры query были изменены после подписания.
  • IP клиента изменился при включенной привязке token_ip.
  • Токен закодирован не в base64url или содержит padding.