Авторизационный бэкенд: доступ к видео по правилам вашей системы

Kinescope позволяет контролировать доступ к видео и трансляциям через внешний авторизационный бэкенд. Это значит, что вы сами решаете, кто может смотреть конкретное видео — на основе правил вашей системы (курсы, подписки, роли и т.д.).

Кому подходит эта статья

• Разработчикам LMS — нужно контролировать доступ к видео по курсам и урокам
• Владельцам платформ с подписками — требуется ограничить доступ по статусу подписки
• Администраторам корпоративных систем — нужно настроить доступ по ролям и группам
• Backend-разработчикам — требуется интегрировать систему контроля доступа с Kinescope

Когда вам нужен авторизационный бэкенд

Вот типичные ситуации, когда это пригодится:

• Доступ только к части видео: пользователь купил курс или пакет, но не имеет доступа ко всей библиотеке.
• Подписка: видео доступны только пока подписка активна (или не истёк пробный период).
• Покупка отдельных уроков: доступ только к конкретным видео, которые пользователь оплатил.
• Корпоративный доступ: доступ по роли в организации (сотрудники, партнёры) или по членству в группе.
• Ограничения по контексту: доступ по IP (IPv4, с точностью до подсети /24), геолокации, времени (окно доступа), устройству или сессии.

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

Как проходит проверка доступа (4 шага)

1. Вы передаёте идентификатор пользователя в плеер Kinescope.
2. Когда пользователь запускает воспроизведение видео или трансляции, Kinescope спрашивает у вашего бэкенда: «Можно ли этому пользователю это смотреть?»
3. Ваш бэкенд проверяет правила (курс, подписка, роль и т.д.) и отвечает: 200 (разрешить) или 403 (запретить).
4. Плеер открывает или блокирует доступ.

Теперь разберём, как это настроить.

Настройка: шаг 1 — передача идентификатора пользователя

При встраивании плеера на сайт передайте токен авторизации через параметр drmauthtoken в URL:

<iframe
  src="https://kinescope.io/embed/pcFNnQGsD59CMKte2SQQaz?drmauthtoken=${user_id}"
  width="640"
  height="360"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media;"
></iframe>

В качестве токена можно использовать любую строку: user_id, JWT-токен или другой идентификатор, который ваш бэкенд сможет проверить. Значение drmauthtoken приходит на ваш бэкенд в поле token без изменений. Если параметр не передан, в token приходит пустая строка.

Рекомендация (безопасность): для продакшена рекомендуем использовать подписанный JWT в drmauthtoken. Это защитит от подмены токена на клиенте. На бэкенде валидируйте подпись JWT и извлекайте user_id.

Для разработчиков: при валидации JWT проверяйте стандартные поля: exp (срок действия), aud (аудитория), iss (издатель) — это повысит безопасность.

Настройка: шаг 2 — подключение вашего бэкенда

Чтобы Kinescope мог обращаться к вашему бэкенду за проверкой доступа, добавьте URL вашего эндпоинта в настройки проекта или рабочей области через API Kinescope.

Важно: API-токен в заголовке Authorization: Bearer должен быть в формате UUID. Получить токен можно в Dashboard Kinescope в разделе Настройки → API-токены. Подробнее об авторизации и обработке ошибок в общих правилах API.

DRM можно настроить на двух уровнях:

• Workspace — применяется ко всем проектам
• Project — применяется к конкретному проекту (переопределяет настройки workspace)

Для проверки доступа Kinescope берёт настройки проекта, в котором лежит видео или трансляция. Если для проекта настройки не заданы, действуют настройки workspace.

Настройка URL авторизационного бэкенда через API:

Для всего workspace:

curl -X PUT "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

Для конкретного проекта:

curl -X PUT "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

Параметры запроса:

• url (обязательный) — URL вашего эндпоинта проверки доступа (куда Kinescope будет отправлять запросы при воспроизведении)
• username (опционально) — логин для Basic Auth к вашему сервису. Если логин задан, Kinescope передаёт логин и пароль в заголовке Authorization: Basic. Если не задан, запрос уходит без этого заголовка
• password (опционально) — пароль для Basic Auth
• strict (опционально) — строгий режим. true — смотреть можно только после ответа 200. false — просмотр запрещает только ответ 403, а ошибки и недоступность вашего бэкенда просмотру не мешают. Подробнее — в разделе «Строгий и нестрогий режим»

Проверка текущих настроек:

# Для workspace
curl -X GET "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

# Для проекта
curl -X GET "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

Все методы настройки описаны в справочнике API.

Важно: Kinescope отправляет на ваш URL POST-запрос с JSON (формат запроса). Решение о доступе принимается по HTTP-коду ответа: 200 — разрешить, 403 — запретить. Тело ответа игнорируется.

Что приходит на ваш бэкенд

Kinescope отправляет POST-запрос на ваш URL авторизации каждый раз, когда плеер запрашивает лицензию для воспроизведения:

• при старте воспроизведения — 1–2 запроса;
• при ротации ключей во время эфира;
• при повторных запросах лицензии плеером.

Ответы не кэшируются, а при таймауте или ошибке запрос не повторяется: на каждый запрос лицензии — одна попытка. Рассчитывайте нагрузку на бэкенд по числу запросов лицензии, а не по числу зрителей.

Пример запроса:

POST /drm/authorize HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic ZHJtX3VzZXI6ZHJtX3Bhc3N3b3Jk

{
  "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
  "ip": "11.22.33.0",
  "type": "vod",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

Заголовки:

• Content-Type: application/json — тело запроса в формате JSON
• Authorization: Basic … — логин и пароль (username, password) из настроек авторизации. Заголовок есть, только если в настройках задан логин

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

Поля video_id в запросе нет: ID видео или трансляции приходит в поле id.

Если правила доступа должны работать и для зрителей с IPv6, стройте их по полям token, id и user_agent, а не по ip.

Трансляции и их записи

Для эфира запрос приходит только у трансляций с включённым шифрованием — с параметром protected: true (Create event). Запросы во время эфира и при просмотре записи различаются:

Пример запроса во время эфира:

{
  "id": "0d5e8f8a-4b7c-4e61-9a3f-2c1b7d9e6a54",
  "ip": "11.22.33.0",
  "type": "live",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

У регулярного события записей несколько — по одной на каждый эфир. Если запись эфира не велась, в вебхуке live.finished поле video_id содержит нулевой UUID.

Что отдавать в ответ

Kinescope принимает решение только по HTTP-коду ответа, тело ответа игнорируется. Ответа Kinescope ждёт 5 секунд — в обоих режимах. Если просмотр разрешён, Kinescope выдаёт ключ дешифровки и плеер начинает воспроизведение. Что происходит при разных ответах, зависит от параметра strict:

Строгий и нестрогий режим

• Строгий (strict: true) — смотреть можно, только если ваш бэкенд ответил 200. Любой другой код или отсутствие ответа за 5 секунд — отказ.
• Нестрогий (strict: false) — просмотр запрещает только ответ 403. Другие коды, отсутствие ответа за 5 секунд и недоступность вашего бэкенда просмотру не мешают.

Для разработчиков: чтобы гарантированно запретить просмотр, возвращайте именно 403 — в нестрогом режиме 401, 404 и 5xx просмотр разрешают.

Как проверить доступ (минимальная схема)

Вот что нужно сделать в вашем обработчике авторизации:

1. Извлечь user_id из token: если используете JWT — валидируйте подпись и извлеките user_id; если передаёте user_id напрямую — просто используйте его.
2. Определить, что смотрит пользователь: по id и type понять, к какому курсу, пакету или разделу относится видео или трансляция.
3. Проверить права в вашей системе: есть ли у пользователя доступ (покупка, подписка, роль, группа и т.д.).
4. Вернуть ответ: 200, если доступ есть, иначе 403.

Коротко в псевдокоде:

user_id = verify_and_extract_user_id(token)
if user_id is empty -> 403

if user_has_access(user_id, id, type) -> 200
else -> 403

Пример: доступ только к купленному курсу

Допустим, у вас на сайте есть курсы, и пользователь купил только один из них. Как проверить доступ к видео этого курса?

Шаг 1: Сопоставьте контент Kinescope с курсом в вашей системе (например, таблица course_videos с полями course_id и kinescope_id). Если в курсе есть трансляции, внесите id события — его возвращают Create event и Get event, — и ID видео с записью каждого эфира: его присылает вебхук live.finished в поле video_id.

Шаг 2: В обработчике авторизации:

• Извлеките user_id из token (валидируйте JWT, если используете).
• По id из запроса найдите course_id.
• Проверьте, что пользователь записан на курс, оплатил его и курс активен.
• Верните 200, если всё ок, иначе 403.

Псевдокод:

course_id = find_course_by_kinescope_id(id)
if course_id is empty -> 403

if enrollment_is_active(user_id, course_id) -> 200
else -> 403

Как это работает (подробнее)

Вот что происходит, когда пользователь смотрит видео:

1. Пользователь заходит на страницу — ваш сайт передаёт токен авторизации (например, user_id или JWT) в плеер Kinescope через параметр drmauthtoken.
2. Плеер запрашивает лицензию — при старте воспроизведения, а не при открытии страницы. Kinescope отправляет вашему бэкенду POST-запрос с JSON, где указаны:
   • токен авторизации (тот, что вы передали в drmauthtoken);
   • ID и тип контента: видео (vod) или эфир трансляции (live);
   • IP-адрес (IPv4 с маской /24) и User-Agent пользователя.
3. Ваш бэкенд проверяет доступ — смотрит правила в вашей системе (курс, подписка, роль и т.д.) и возвращает ответ:
   • HTTP 200 — доступ разрешён, сервер лицензий выдаёт ключ дешифровки, видео становится доступным.
   • HTTP 403 — доступ запрещён, видео не воспроизводится.
   • Другой код или нет ответа за 5 секунд — результат зависит от режима strict.
4. Плеер получает ответ — открывает или блокирует доступ к видео.

Всё! Теперь вы можете контролировать доступ к видео по любым правилам вашей системы.

Что дальше?

После настройки авторизационного бэкенда рекомендуем:

1. DRM-шифрование файлов — дополнительная защита контента
2. Ограничение доступа к видео — другие способы ограничения доступа
3. Общие правила API — авторизация и формат запросов

Остались вопросы? Напишите в чат поддержки — специалисты помогут!