Авторизация просмотра

Настройка всех пяти режимов auth_backend с примерами, передача токена плееру, поведение по протоколам и типичные ошибки интеграции.

Авторизация просмотра закрывает всю медиа-выдачу: HLS, LL-HLS, DASH, MSE-WS, HTTP-TS, WHEP, RTSP, выдачу по RTMP, превью-кадры, DVR, таймшифт, экспорт клипов и видео по запросу. Она же закрывает приём публикации — см. Авторизация публикации.

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

Общая форма#

Режим задаётся единственным блоком — на сервер один бэкенд:

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

Ошибки проверки конфигурации приводятся дословно:

auth_backend.type must be one of none|internal|hs256|jwks|http (got "x")
auth_backend type "jwks" requires a url
auth_backend type "hs256" requires a secret
auth_backend type "internal" needs at least one `principal` block

Режим none — блока нет#

# либо явно:
auth_backend { type none; }

Медиа открыто всем. Никаких предупреждений при старте про открытые потоки не печатается — проверяйте это аудитом конфигурации.

Режим internal — офлайн-список принципалов#

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

auth_backend { type internal; }

principal alice {
    pass       hunter2;                    # либо sha256:<hex>
    permission read cam hls;               # действие · путь · протоколы
}

principal svc {
    token      s3cr3t-service-token-value; # непрозрачный токен
    permission read     cam;
    permission playback cam;
}

Проверено на стенде:

# токен принимается и строкой запроса, и заголовком
curl -s -o /dev/null -w '%{http_code}\n' \
  "http://media.example.com:8080/cam/index.m3u8?token=s3cr3t-service-token-value"
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Authorization: Bearer s3cr3t-service-token-value' \
  http://media.example.com:8080/cam/index.m3u8
# пара логин/пароль — обычная Basic-аутентификация
curl -s -o /dev/null -w '%{http_code}\n' -u alice:hunter2 \
  http://media.example.com:8080/cam/index.m3u8
# без учётных данных
curl -s -o /dev/null -w '%{http_code}\n' http://media.example.com:8080/cam/index.m3u8

200
200
200
401

Пароль можно хранить хешем — сервер сравнивает его константным временем:

printf '%s' 'hunter2' | sha256sum | cut -d' ' -f1

f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7

principal alice { pass sha256:f52fbd32b2b3b86ff88ef6c490628285f482af15ddcb29541f94bcf526a3f6c7; }

Полный синтаксис permission и ограничения — Поля токена.

Режим hs256 — JWT на общем секрете#

Основной рабочий режим для временных ссылок: ваш бэкенд подписывает JWT тем же секретом, что задан на сервере, и подставляет его в URL плеера.

auth_backend {
    type        hs256;
    secret      "очень-длинный-общий-секрет";
    issuer      "https://idp.example";   # необязательно
    audience    "sirinvideo";            # необязательно
    perms_claim "grants";                # по умолчанию "grants"
}

Полезная нагрузка минимального токена:

{"sub":"viewer-42","exp":1787200000,
 "grants":[{"action":"read","path":"cam","protocols":["hls"]}]}

Алгоритм жёстко закреплён: заголовок обязан содержать ровно HS256. Попытка alg: none → 401 (проверено).

Готовый скрипт выпуска — Генераторы токенов.

Режим jwks — асимметричные токены внешнего поставщика#

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

auth_backend {
    type        jwks;
    url         https://idp.example/.well-known/jwks.json;
    issuer      "https://idp.example";
    audience    "sirinvideo";
    perms_claim "grants";
    # revoked_url https://idp.example/revoked;   # список отозванных jti
    # tls_verify  insecure;                      # только для самоподписанного сертификата у источника ключей
}

Поддерживаются RS256 (RSA + SHA-256) и ES256 (ECDSA P-256). Алгоритм привязан к типу ключа: RS256 проверяется только ключом RSA, ES256 — только EC.

Ключи тянет фоновая задача:

[authz] auth_backend type "jwks": no keys cached (fetch pending/failed) — denying (fail-closed)

[authio] jwks: loaded 2 key(s) from https://idp.example

[authio] jwks: fetch failed (https://idp.example): <текст ошибки> — keeping the last-good set, retrying

Режим http — ваша внешняя служба#

Сервер обращается к вашему адресу методом POST на каждое установление сессии (не на сегмент — за это отвечает билет).

auth_backend { type http; url https://auth.example/authorize; }

Тело запроса — снятый со стенда payload:

{"ip":"203.0.113.7","user":"","password":"","token":"allow-all","action":"read",
 "privilege":"live","path":"cam","labels":["site-north"],"protocol":"hls",
 "query":"token=allow-all","user_agent":"curl/8.18.0"}

Поле privilege уточняет действие до конкретной поверхности: live, dvr, export, preview для просмотра и publish для приёма публикации.

Интерпретация вашего ответа:

Ограничения: тело ответа не более 64 КиБ, таймаут 5 секунд (не настраивается), не более 256 одновременных вызовов на ядро.

Пример минимальной службы на стандартной библиотеке Python — Генераторы токенов.

Исключения: public_paths#

public_paths health lobby/*;

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

Как отдать токен плееру#

Три рабочих способа, по убыванию удобства:

1. Строка запроса на плейлисте. Ваш бэкенд отдаёт готовую ссылку: http://media.example.com:8080/cam/index.m3u8?token=$TOKEN. Дальше плеер идёт по URI из плейлиста, в которые сервер уже вплёл ?ssid=. Это единственный способ, работающий для MSE-WS в браузере: заголовки на WebSocket задать нельзя.
2. Заголовок Authorization: Bearer. Годится для нативных приложений и серверных интеграций, где заголовками управляете вы.
3. Basic-аутентификация — только для режимов internal и http.

curl -s -o /dev/null -w '%{http_code}\n' \
  "http://media.example.com:8080/cam/v0/1787143547.m4s?token=$TOKEN"
curl -s -o /dev/null -w '%{http_code}\n' \
  "http://media.example.com:8080/cam/v0/1787143547.m4s?ssid=<ssid-из-плейлиста>"

401
200

Поведение по протоколам#

Сегменты, init-объекты и части всех перечисленных HTTP-протоколов проверяются только билетом.

Что стоит знать по отдельным протоколам#

• HLS и DASH делят одни и те же объекты сегментов, но билеты у них разные: билет, выпущенный на index.m3u8, не откроет сегмент, запрошенный как DASH, и наоборот.
• MSE-WS: браузер не может задать заголовок на WebSocket, поэтому на практике остаётся ?token=. Есть отдельная проба HEAD /{поток}/mse.ws — она отвечает 204, 401 или 403 и позволяет проверить право до открытия сокета.
• RTSP: грант проверяется один раз, на первом запросе с URI (DESCRIBE). Учётные данные принимаются и заголовком Authorization (Basic или Bearer), и как ?token= прямо в RTSP-URI. SETUP и PLAY после допуска идут по установленной сессии.
• RTMP-выдача: заголовков нет, поэтому учётные данные едут только в строке запроса URL — rtmp://media.example.com/live/cam?token=$TOKEN. Билетов RTMP не использует: одно соединение, авторизуемое один раз.
• Превью-кадр требует отдельной привилегии preview и не выпускает билет — это одиночный объект.
• Экспорт клипа требует привилегии export. Обычное разрешение с action: playback и подходящим путём открывает и архив, и экспорт; разрезать их можно только компактным грантом по метке — см. Метки потоков.

Грабли#

Билет привязан к User-Agent#

Смена User-Agent внутри одной сессии — 403. Это ловит три реальных сценария: «скачаю ссылку из браузера через curl», прокси, переписывающий заголовок, и клиент, обновившийся посреди сессии.

UA='Mozilla/5.0 MyPlayer'
curl -s -o /dev/null -w '%{http_code}\n' -A "$UA"      "http://media.example.com:8080/cam/v0/$SEG"
curl -s -o /dev/null -w '%{http_code}\n' -A "Other/1.0" "http://media.example.com:8080/cam/v0/$SEG"

200
403

Тот же эффект даёт session_keys { bind_ip on; } при смене адреса — учитывайте это для мобильных клиентов и сетей за CG-NAT.

Включение авторизации отключает кэширование сегментов#

Понижение до Cache-Control: no-store вызывает любой из двух факторов: у потока задан allowed_referers, или включён auth_backend и путь не входит в public_paths.

Проверено на одном и том же объекте:

# сервер без auth_backend
curl -sI "http://media.example.com:8080/cam/v0/init.mp4" | grep -i cache-control
# сервер с auth_backend
curl -sI "http://media.example.com:8080/cam/v0/init.mp4?ssid=$SSID" | grep -i cache-control

Cache-Control: public, max-age=31536000, immutable
Cache-Control: no-store

Понижение применяется одинаково на всех трёх ветках выдачи — живой, DVR и видео по запросу.

principal any превращает все 401 в 403 по всему серверу#

Принципал с именем any совпадает с любым запросом, поэтому отказ всегда классифицируется как «прав нет», а не «предъявите данные». Проверено:

Клиенты, которые ждут 401, чтобы предложить ввести пароль, ломаются молча — плеер просто покажет ошибку.

За обратным прокси обязателен trusted_proxies#

Заголовки X-Forwarded-For, Forwarded и X-Real-IP читаются, только если непосредственный клиент перечислен в trusted_proxies. Без этого привязка по IP — и в токене, и в билете — закрепится на адресе прокси: либо всё сломается, либо «привязка» перестанет что-либо значить.

Троттлинг бьёт по всем за общим NAT#

Восемь неудачных попыток за 60 секунд с одного адреса → блокировка с ответом 429 throttled и заголовком Retry-After. Отказы вида 403 (подпись верна, прав нет) троттл не кормят намеренно — иначе плеер, опрашивающий недоступный ему поток, заблокировал бы себе остальные.

caps — это не контроль доступа#

stream cam { caps hls mse-ws; } ограничивает только вкладки встроенного плеера. Поток с caps hls; по-прежнему отдаётся по MSE-WS, DASH и RTSP.

Рецепты#

Закрыть все потоки и выдавать временные ссылки#

http 8080;

auth {                                   # иначе панель управления открыта всем
    admin_password  "длинный-пароль-администратора";
    session_secret  "общий-секрет-32-и-более-символов";
}

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

session_keys { ttl 3600; }               # срок билета сессии

stream cam { input rtsp://admin:пароль@10.0.0.10:554/Streaming/Channels/101; }

Ссылку зрителю выдаёт ваш бэкенд: подписывает JWT тем же секретом и отдаёт http://media.example.com:8080/cam/index.m3u8?token=$TOKEN.

Токен на один поток на N минут#

{"sub":"viewer-42","exp":1787200000,
 "grants":[{"action":"read","path":"cam","protocols":["hls"]}]}

Ограничение по адресу зрителя#

{"exp":1787200000,"ip":"203.0.113.7",
 "grants":[{"action":"read","path":"cam","protocols":["hls"]}]}

{"exp":1787200000,"net":["203.0.113.0/24","2001:db8::/32"],
 "grants":[{"action":"read","path":"cam","protocols":["hls"]}]}

Оба варианта проверены: попадание → 200, промах → 403. Третий, независимый механизм — session_keys { bind_ip on; }: он привязывает к адресу сам билет, то есть и все сегменты.

Публичный поток-исключение#

public_paths lobby/*;
stream lobby/hall { input rtsp://10.0.0.10:554/live; }

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

# 1. плейлист без токена
curl -s -o /dev/null -w '%{http_code}\n' http://media.example.com:8080/cam/index.m3u8
# 2. плейлист с токеном
curl -s -o /dev/null -w '%{http_code}\n' "http://media.example.com:8080/cam/index.m3u8?token=$TOKEN"
# 3. заголовок кэширования на init-объекте
curl -sI "http://media.example.com:8080/cam/v0/init.mp4?ssid=$SSID" | grep -i cache-control

401
200
Cache-Control: no-store