Поля токена

Полный справочник claim'ов JWT зрителя, полей билета сессии и директив внутренних принципалов — с типами, умолчаниями и поведением при отсутствии.

Эта страница — справочник. Настраиваемых артефактов три, и они не взаимозаменяемы.

Ещё два артефакта существуют, но снаружи не настраиваются вовсе: короткоживущий медиа-грант панели управления (срок жёстко 300 секунд) и токен администратора для /api/v1 (срок 12 часов) — см. Доступ к админке и API.

JWT зрителя: заголовок#

JWT зрителя: полезная нагрузка#

Обязателен по существу только claim с правами — без него ни один путь не откроется. Все остальные поля необязательны, и у каждого есть смысл «если не передать».

Элемент массива прав: объект#

{"action":"read","path":"cam","labels":["site-north"],"protocols":["hls","mse-ws"]}

* Нужно хотя бы одно из path / labels. Разрешение без обоих не открывает ничего: {"action":"read"} → 403 (проверено). «Все потоки» пишется явно: {"action":"read","path":"*"}.

Элемент массива прав: строка (компактный грант)#

<метка-b64u22>.<маска-hex> либо *.<маска-hex> — выдаёт биты привилегий, а не действия. Подробно, с таблицей масок и примерами, — Метки потоков.

Некорректная строка молча отбрасывается: токен остаётся валидным, но это право не считается.

Билет сессии ?ssid=#

Поля самого билета не настраиваются — он выпускается сервером. Настраивается его политика:

session_keys {
    ttl              3600;
    vod_session_ttl  86400;
    bind_ip          off;
    secret           "общий-секрет-подписи-билетов";
}

• ttl — срок жизни билета. Продлевается скользяще, пока плеер опрашивает плейлист, но никогда не дольше, чем exp гранта, которым билет был выпущен.
• vod_session_ttl — потолок продолжения сессии видео по запросу. Значение вне диапазона — ошибка конфигурации: session_keys.vod_session_ttl must be 300..=604800 seconds; got N.
• bind_ip — вносит адрес клиента в подпись билета. Мобильный клиент, сменивший сеть, получит 403 и переустановит сессию.
• secret — если пусто, ключ выводится из auth.session_secret; если и его нет, генерируется случайный секрет на эту загрузку (билеты не переживут перезапуск). Смена значения немедленно обесценивает все выданные билеты.

Ярус билетов включается автоматически вместе с любым режимом auth_backend и отключить его нельзя.

Из чего состоит билет#

Ничего из перечисленного не настраивается, но знать состав полезно при диагностике: билет несёт номер эпохи ключа, одноразовый идентификатор сессии, срок, код протокола, снимок маски привилегий и подпись. В подпись дополнительно входят — но не хранятся в самом билете — путь потока, хеш User-Agent и адрес клиента (если включён bind_ip). Поэтому билет непереносим между потоками, браузерами, протоколами и классами привилегий.

Внутренние принципалы (type internal)#

principal alice {
    pass       hunter2;
    permission read     cam        hls;
    permission playback dvr/cam1   hls rtsp;
    permission read     label=north label=vip;
}

Правила разбора строки permission: первый токен — действие; следующий считается путём, если он не начинается с label=; все оставшиеся label= — метки, всё прочее — протоколы. Путь и метки складываются по ИЛИ.

Принципалу нужен либо token, либо пара имя + pass, либо имя any; иначе конфигурация не пройдёт проверку: principal #0: needs a `token`, or a `user`+`pass`, or `user any` .

Контракт ответа внешней службы (type http)#

Здесь токен придумываете вы — сервер лишь пробрасывает предъявленное клиентом как есть. Настраивается не токен, а ответ вашей службы:

Схема строгая: неизвестное поле внутри permissions отвергает весь ответ. Пустое тело с кодом 2xx означает «разрешить ровно запрошенную пару действие + путь».

Что настроить нельзя#