Токены доступа¶

media.access.token

Для новых интеграций используйте JWT зрителя. Ваше приложение проверяет права зрителя и через административный API central получает подписанный токен на просмотр. Плеер предъявляет этот токен стримеру, а стример проверяет его локально, без запроса к приложению или HTTP-бэкенду авторизации.

Один JWT действует на всех эджах кластера, которым доставлен соответствующий публичный ключ. При переходе на другой эдж зрителю не нужен новый токен. Такой допуск устраняет поток запросов авторизации при массовом начале просмотра и снимает зависимость допуска каждого зрителя от доступности и задержки внешнего HTTP-бэкенда.

HTTP-бэкенд авторизации — устаревший механизм, не рекомендуемый для новых интеграций. Он сохраняется для совместимости.

Как передается токен¶

Токен принимается двумя способами:

• Параметр URL — ?token=<token>, имеет приоритет.
• Заголовок — Authorization: Bearer <token>, используется, если параметра token в URL нет.

Для HLS откройте мастер-плейлист с токеном: Sapsan добавляет его во вложенные URL плейлистов и медиа. Если используете заголовок, клиент должен передавать его в защищённых запросах. Не передавайте плееру административный ключ: он нужен только вашему приложению для выдачи JWT.

Получить JWT через central¶

Предварительно создайте стрим news и подключите стримеры к central. Дождитесь доставки конфигурации и публичных ключей на эджи. В примере нужны curl и jq; замените домены и административный ключ своими значениями.

CENTRAL_URL='https://central.example.com'
EDGE_1='https://edge1.example.com'
EDGE_2='https://edge2.example.com'
ADMIN_KEY='replace-with-management-api-key'

ISSUED=$(curl --fail-with-body --silent --show-error \
  -X POST "$CENTRAL_URL/central/api-v4/play-sessions/grants" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"streams":["news"],"user_id":"viewer-42","ttl_secs":3600,"max_concurrent":1}')

TOKEN=$(printf '%s' "$ISSUED" | jq -er '.token')
JTI=$(printf '%s' "$ISSUED" | jq -er '.jti')

Central создаёт грант — запись о выданном доступе — и возвращает 201 Created. Ответ содержит поля гранта и token на одном уровне. Поле jti — идентификатор гранта, expires_at — время окончания доступа в UTC. Сам JWT возвращается только при создании; чтение гранта через API его не возвращает.

Поля запроса:

Просмотр и переход между эджами¶

Получите HLS-плейлист с первого эджа, затем со второго, используя тот же TOKEN:

curl --fail-with-body --silent --show-error \
  "$EDGE_1/streaming/v/news/index.m3u8?token=$TOKEN"

curl --fail-with-body --silent --show-error \
  "$EDGE_2/streaming/v/news/index.m3u8?token=$TOKEN"

Эти команды получают плейлисты; для воспроизведения откройте соответствующий URL в HLS-плеере. Оба эджа должны уметь отдавать стрим news. Проверка JWT сама по себе не размещает стрим и не обеспечивает доступность его источника.

Для выбора стримера балансировщиком используйте https://central.example.com/playback/v/news/index.m3u8?token=<JWT>. Доступность такого URL зависит и от central: он выбирает стример и перенаправляет запрос либо проксирует медиа. Прямой URL эджа проверяется самим стримером.

Переход на другой эдж может создать новую локальную сессию. Central сопоставляет сессии по гранту и учитывает активность, чтобы переставший получать медиа старый эдж не занимал лимит бесконечно. Подробнее — кластерная сессия и переход между эджами.

Охват и срок действия¶

Слушатель MoQ пока не подключён к этому механизму авторизации.

JWT подписан Ed25519 с алгоритмом EdDSA; kid в заголовке выбирает публичный ключ. В содержимом JWT находятся:

• jti — идентификатор гранта.
• user_id — идентификатор зрителя.
• exp — окончание действия в Unix-секундах.
• streams — разрешённые имена медиа.
• bind_ip — IP или сеть, если привязка задана.

Для прямого эфира и архива стрима используется одно имя: news. Для VOD укажите vod/<asset-id>: грант покрывает файлы этого ассета, независимо от корня хранения и имени файла. Стандартный claim aud для такого охвата не используется. Лимит max_concurrent находится в реестре central, а не внутри JWT.

Эдж проверяет подпись, срок и охват локально; заданную IP-привязку тоже проверяет локально. На рассинхронизацию часов предусмотрен допуск 30 секунд. Невалидный JWT отклоняется без попытки авторизовать его через HTTP-бэкенд. После истечения срока следующие HTTP-запросы отклоняются; продление требует нового гранта. Мгновенный обрыв уже открытого непрерывного HTTP-ответа не гарантируется — это ограничение описано в авторизации сессии. Планируйте обновление токена в приложении, если просмотр может длиться дольше его срока.

Лимит сессий и отзыв доступа¶

max_concurrent действует на грант во всём кластере. Central получает сведения о сессиях и асинхронно завершает самые старые активные сессии сверх лимита; новая сессия остаётся. Это не мгновенный запрет второго запроса на каждом эдже. Лимит считает серверные сессии, а не гарантированно разные физические устройства: запросы с одинаковыми медиа, IP и грантом могут объединяться в одну HTTP-сессию.

Изменить лимит без перевыпуска JWT:

curl --fail-with-body --silent --show-error \
  -X PATCH "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"max_concurrent":2}'

Отозвать грант целиком:

curl --fail-with-body --silent --show-error \
  -X DELETE "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY"

Отзыв возвращает 204 No Content. Central доставляет его стримерам отдельным каналом терминаций. Получив отзыв, стример закрывает сессии этого гранта и отклоняет новые обращения. Отзыв не является мгновенной общей проверкой на каждом медиазапросе: при потере связи с central эдж не узнает о новом отзыве до восстановления канала.

Доставка ключей и работа без связи с central¶

Central хранит приватный ключ подписи и доставляет стримерам публичные ключи в auth.ticket_keys вместе с конфигурацией. При незаданном списке ключей в политике central подставляет свои ключи автоматически. Эдж с публичным ключом может проверять JWT, но не может выпускать новые токены.

Проверка на уже настроенном эдже не требует доступного central. Пока JWT действителен и медиа доступны, локальный допуск продолжает работать с полученными ключами. При этом от central зависят:

• Выдача новых грантов — для неё нужны API central и его хранилище.
• Новые ключи и изменения политики — они должны дойти до стримеров.
• Отзывы и общий лимит сессий — нужны канал терминаций и сведения о сессиях.
• Балансировка через /playback — её выполняет central.

При ротации старый публичный ключ должен оставаться доступным для проверки ещё действующих JWT. Не удаляйте его раньше окончания срока таких токенов. Поддержка нескольких ключей не означает наличия публичного API автоматической ротации.

Статические токены¶

Статические токены сохраняются для совместимости и простых существующих установок. Они не заменяют выдачу отдельных грантов зрителям:

auth:
  play_tokens:
  - viewer-secret-1
  publish_tokens:
  - publisher-secret-1

• play_tokens — токены на просмотр.
• publish_tokens — токены на публикацию.

JWT зрителя предназначен для просмотра; не используйте его как разрешение на публикацию. В управляемом кластере политику auth доставляет central; YAML выше показывает структуру настроек для отдельного стримера.

Параметр opaque_tokens по умолчанию равен true ради совместимости. После миграции его можно установить в false, чтобы отключить общий путь непрозрачных токенов и HTTP-бэкендов. Токены просмотра в конфиге отдельных стримов при этом продолжают работать. Явный open_playback по-прежнему открывает просмотр. Проверяйте всю политику доступа при миграции.