Метки потоков (labels)

Как выдать доступ сразу группе потоков одной строкой в токене — и почему uuid с дефисами в JWT даёт 403.

Выдавать права по имени потока удобно, пока потоков десять. На тысяче камер токен, перечисляющий пути, становится неуправляемым: каждое добавление камеры требует перевыпуска всех токенов.

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

Ядро не приписывает метке никакого смысла: это не организация, не тег и не иерархия. Что она означает, решаете вы.

Как назначить метку потоку#

stream camA {
    input  rtsp://admin:пароль@10.0.0.10:554/Streaming/Channels/101;
    labels site-north tier-gold <UUID>;
}

Метки — единственная часть блока потока, которая не входит в его отпечаток перезапуска. Поэтому их правка применяется вживую: поток не переподключается, зрители не разрываются, а снятая метка перестаёт авторизовывать со следующего медиа-запроса.

Главная ловушка: uuid канонизируется в конфигурации, но не в токене#

Если метка выглядит как uuid, сервер приводит её к компактной 22-символьной форме base64url — чтобы два написания одного и того же uuid были одной идентичностью. Это преобразование применяется к меткам потоков и к меткам в конфигурации, но НЕ к меткам внутри JWT: их сравнивают байт в байт с тем, что уже лежит в памяти сервера.

в конфигурации:  labels 3f2504e0-4f89-11d3-9a0c-0305e82c3301;
в памяти:        PyUE4E-JEdOaDAMF6CwzAQ
в токене нужна:  PyUE4E-JEdOaDAMF6CwzAQ      ← а не форма с дефисами

Проверено на стенде, поток с меткой-uuid из примера выше:

Преобразование — это base64url без выравнивания от 16 байт uuid:

python3 -c "
import base64, sys
u = sys.argv[1].replace('-', '')
print(base64.urlsafe_b64encode(bytes.fromhex(u)).rstrip(b'=').decode())
" 3f2504e0-4f89-11d3-9a0c-0305e82c3301

PyUE4E-JEdOaDAMF6CwzAQ

Если вы не используете uuid в метках, ловушки нет: site-north остаётся site-north везде.

Две формы права по метке#

Форма 1 — обычное разрешение с полем labels#

Выдаёт действие (read, playback, publish):

{"action":"read","labels":["site-north"],"protocols":["hls"]}

Совпадение — точное строковое равенство с любой из меток потока. Ни глоба, ни префикса, ни регистронезависимости: site-* и SITE-NORTH не совпадут с site-north (проверено, 403).

Поле path можно не указывать вовсе — тогда правило работает исключительно по меткам.

Форма 2 — компактный грант-строка#

Выдаёт биты привилегий (live, dvr, export, preview) и записывается одной строкой <метка>.<маска-hex>:

{"grants":["PyUE4E-JEdOaDAMF6CwzAQ.03", "*.20"]}

Метка здесь обязана быть корректной 22-символьной формой base64url; * означает «любой поток». Некорректная строка молча отбрасывается — токен остаётся валидным, но это право в нём просто не считается.

Обе формы можно смешивать в одном массиве прав.

Сопоставление: всюду ИЛИ#

Пересечения (И) в системе меток нет нигде. Сужают доступ только action, protocols, привязка к IP и замок Referer из токена — но не метки.

Отсюда важное: приоритета у путей и меток нет и запретить меткой нельзя. Метка умеет только добавлять доступ.

Поток без меток#

Множество меток пусто, поэтому:

• правило только по меткам такому потоку не подойдёт — 403;
• правило по пути (path) работает как обычно;
• компактный грант *.<маска> сработает: подстановочный знак пересекается с любым набором меток, включая пустой.

Метки и public_paths#

Механизмы независимы и срабатывают на разных этапах. public_paths проверяется первым и полностью снимает авторизацию для пути; метки участвуют позже, когда бэкенд уже разбирает грант.

Практически это значит: метка не может сделать поток публичным, а public_paths не смотрит на метки — только на путь. Есть и разница в кэшировании: путь из public_paths сохраняет кэшируемость сегментов, «открытый меткой» — нет (см. Авторизация просмотра).

Разобранные примеры#

Конфигурация во всех примерах:

auth_backend { type hs256; secret "секрет-подписи-токенов-зрителей"; }

stream camA { input rtsp://10.0.0.10:554/live; labels <UUID> site-north; }
stream camB { input rtsp://10.0.0.11:554/live; labels site-north; }
stream camC { input rtsp://10.0.0.12:554/live; }

где <UUID> = 3f2504e0-4f89-11d3-9a0c-0305e82c3301. После загрузки конфигурации метки camA — это ["PyUE4E-JEdOaDAMF6CwzAQ", "site-north"]: uuid канонизирован, набор отсортирован и очищен от повторов.

Пример 1 — доступ к группе по общей метке#

{"exp":1787200000,"grants":[{"action":"read","labels":["site-north"]}]}

Пример 2 — метка-uuid записана не в той форме#

{"exp":1787200000,"grants":[{"action":"read","labels":["3f2504e0-4f89-11d3-9a0c-0305e82c3301"]}]}

Тот же uuid в форме ["PyUE4E-JEdOaDAMF6CwzAQ"] → camA 200, camB и camC 403.

Пример 3 — путь и метка в одном разрешении складываются по ИЛИ#

{"exp":1787200000,"grants":[{"action":"read","path":"camB","labels":["PyUE4E-JEdOaDAMF6CwzAQ"]}]}

Пример 4 — компактные гранты разрезают привилегии#

{"exp":1787200000,"grants":["*.02"]}   // только dvr
{"exp":1787200000,"grants":["*.10"]}   // только export
{"exp":1787200000,"grants":["*.12"]}   // dvr и export

Живой просмотр требует бита live (01) — ни dvr, ни export его не дают. Это единственный способ выдать право «только скачать клип» без права смотреть.

Проверка#

curl -s -o /dev/null -w '%{http_code}\n' \
  "http://media.example.com:8080/camA/index.m3u8?token=$TOKEN"
curl -s -o /dev/null -w '%{http_code}\n' \
  "http://media.example.com:8080/camC/index.m3u8?token=$TOKEN"

200
403