# Ссылка для входа в Speak с ролью администратора Kinescope позволяет заранее задать роль участника в ссылке на комнату Speak. Вы подписываете JWT-токен (JSON Web Token) на своём сервере и добавляете его к ссылке — человек открывает её и попадает в комнату сразу администратором. Это значит, что вам не нужно выдавать права вручную в интерфейсе: роль приходит вместе со ссылкой, а решение о том, кому её отправить, принимает ваша система. ## **Кому подходит эта статья** * **Разработчикам платформ** — нужно выдавать ссылки на встречи из LMS, CRM или личного кабинета * **Backend-разработчикам** — требуется подписывать токены с ролью на своей стороне * **Интеграторам вебинаров** — нужно, чтобы ведущий заходил в комнату с полными правами ## **Когда вам нужна ссылка с ролью для Speak** Вот типичные ситуации, когда это пригодится: - **Ведущий заходит из вашего интерфейса** — преподаватель нажимает «Начать урок» в вашей системе и попадает в комнату администратором - **Автоматическая рассылка ссылок** — расписание встреч живёт в вашей системе, и ссылки для ведущих генерируются без участия человека - **Несколько ведущих в одной комнате** — правами управляет ваша система, а не владелец комнаты - **Без ручной выдачи прав** — никто не назначает роли в интерфейсе Speak перед каждой встречей Если хотя бы один из этих сценариев вам знаком — читайте дальше. ## **Как работает вход по ссылке с ролью (4 шага)** Схема та же, что и в чате трансляций: асимметричная криптография RSA, приватный ключ остаётся у вас. 1. **Вы создаёте пару ключей** (приватный и публичный) на вашем сервере 2. **Публичный ключ сохраняется в Kinescope** через API (приватный остаётся только у вас) 3. **Ваш сервер создаёт JWT-токен** с полями `aud`, `room_id` и `role` и подписывает его приватным ключом 4. **Пользователь открывает ссылку с токеном** — Kinescope проверяет подпись публичным ключом и пускает его в комнату с указанной ролью Теперь разберём, как это настроить. ## **Шаг 1 — ключи для подписи** Ключи для Speak генерируются и сохраняются точно так же, как для чата трансляций. Если вы уже настраивали JWT для чата, переходите сразу к шагу 2 — новый ключ не нужен. Что нужно сделать: 1. **Сгенерировать пару ключей RSA** и подготовить публичный ключ в формате JWK — [генерация ключей](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#настройка-шаг-1--генерация-ключей) 2. **Сохранить публичный ключ в Kinescope** через `POST /v1/jwk` — [сохранение публичного ключа](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#сохранение-публичного-ключа-в-kinescope) 3. **Проверить список активных ключей** при необходимости — [управление ключами](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#управление-ключами) > **Информация:** **Один ключ на оба сценария:** тот же JWK подходит и для чата трансляций, и для Speak. Kinescope различает назначение токена по полю `aud` внутри него, а не по ключу. ## **Шаг 2 — токен для Speak** Создайте JWT-токен и подпишите его приватным ключом по алгоритму RS256. Идентификатор ключа передайте в заголовке токена в поле `kid`. ### **Обязательные поля** - **`aud`** (audience) — значение `"speak"`. По нему Kinescope понимает, что токен предназначен для видеовстречи, а не для чата. - **`room_id`** — код комнаты из её ссылки, например `jqi-qhua-glk`. Должен совпадать с кодом в адресе, по которому пойдёт пользователь. - **`role`** — роль участника. Сейчас поддерживается значение `"admin"` — участник получает права администратора комнаты. Где взять код комнаты: он стоит в конце ссылки на комнату в интерфейсе Speak. Через API его вернут поля `code` и `link` в ответе `GET /v1/speak/rooms` — смотрите [справочник API](https://docs.kinescope.ru/api/#v1-speak-rooms). ### **Стандартные JWT-поля (рекомендуется)** Добавьте `exp`, `iat` и `nbf` — они работают так же, как в чате трансляций, и проверяются при валидации токена. Подробности — в разделе [стандартные JWT-поля](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#стандартные-jwt-поля-рекомендуется). ### **Пример payload** ```json { "aud": "speak", "room_id": "jqi-qhua-glk", "role": "admin", "iat": 1703500800, "exp": 1703504400 } ``` ### **Пример генерации токена** ```go package main import ( "crypto/rsa" "time" "github.com/golang-jwt/jwt/v5" ) type SpeakClaims struct { RoomID string `json:"room_id"` // код комнаты из ссылки Role string `json:"role"` // admin jwt.RegisteredClaims } // Генерация токена для входа в комнату Speak func generateSpeakJWT(privateKey *rsa.PrivateKey, kid, roomID, role string) (string, error) { now := time.Now() claims := SpeakClaims{ RoomID: roomID, Role: role, RegisteredClaims: jwt.RegisteredClaims{ Audience: []string{"speak"}, // обязательно "speak" IssuedAt: jwt.NewNumericDate(now), ExpiresAt: jwt.NewNumericDate(now.Add(1 * time.Hour)), }, } token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims) token.Header["kid"] = kid // Key ID сохранённого в Kinescope публичного ключа return token.SignedString(privateKey) } ``` Общая механика подписи и примеры библиотек для других языков — в разделе [пример генерации JWT](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#пример-генерации-jwt). ## **Ссылка для входа** Добавьте готовый токен к ссылке на комнату параметром `token`: ``` https://speak.kinescope.io/{{room_code}}?token={{jwt}} ``` **Пример:** ``` https://speak.kinescope.io/jqi-qhua-glk?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0yMDI0LTEyLTI1In0.eyJhdWQiOiJzcGVhayIsInJvb21faWQiOiJqcWktcWh1YS1nbGsiLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3MDM1MDA4MDAsImV4cCI6MTcwMzUwNDQwMH0.signature_here ``` Готово! Теперь участник, открывший такую ссылку, попадёт в комнату с ролью администратора. ## **Безопасность** > **Внимание:** **Токен с ролью `admin` даёт полные права в комнате.** Выдавайте такие ссылки только тем пользователям, которых ваша система уже авторизовала, и не публикуйте их в открытом доступе. Ссылка с токеном — это и есть пропуск: любой, кто её получит, войдёт администратором. Что стоит соблюдать: - **Короткий срок жизни токена** — ставьте `exp` на время, близкое к длительности встречи, а не на месяцы вперёд - **Генерация на бэкенде** — приватный ключ не должен попадать в браузер или мобильное приложение - **Никаких токенов в логах и аналитике** — ссылка с токеном не должна утекать в системы, где её увидят посторонние - **Отдельная ссылка на каждого ведущего** — так проще отозвать доступ и разобраться, кто чем воспользовался Регламент обновления ключей и действия при утечке приватного ключа описаны в статье про чат: [ротация ключей](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#ротация-ключей) и [действия при компрометации ключа](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#действия-при-компрометации-ключа). ## **Решение проблем** ### **Токен не принимается системой** **Проблема:** пользователь открывает ссылку, но не попадает в комнату или заходит без роли администратора. Проверьте по порядку: 1. **Поле `aud`** — должно быть строго `"speak"` в нижнем регистре. Токен для чата (`"chat"`) в Speak не подойдёт. 2. **Поле `room_id`** — код комнаты в токене должен совпадать с кодом в адресе ссылки. Например, для `https://speak.kinescope.io/jqi-qhua-glk` в токене нужен `"room_id": "jqi-qhua-glk"`. 3. **Поле `role`** — значение `"admin"` в нижнем регистре. 4. **Срок действия токена** — проверьте `exp` и синхронизацию системного времени на сервере (NTP). 5. **Публичный ключ** — он должен быть загружен в Kinescope, не истёкшим, а токен подписан парным ему приватным ключом по алгоритму RS256. Проверить структуру и подпись токена локально до отправки пользователю поможет пример из раздела [как проверить валидность токена](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#как-проверить-валидность-токена). Частые ошибки при работе с ключами разобраны там же, в разделе [решение проблем](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/#решение-проблем). Если проблема не решилась, напишите в [техническую поддержку](https://t.me/kinescope_bot) и приложите код комнаты, пример токена (чувствительные данные можно замаскировать) и описание шагов воспроизведения. ## Что дальше? После настройки ссылок с ролью рекомендуем: 1. **[Что такое Speak](https://docs.kinescope.ru/speak-beta/chto-takoe-speak/)** — возможности видеовстреч и запись в каталог 2. **[JWT-аутентификация для чата трансляций](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/jwt-autentifikatsiya-dlya-chata-translyatsiy/)** — тот же механизм ключей для чата 3. **[Справочник API по Speak](https://docs.kinescope.ru/api/#v1-speak-rooms)** — создание комнат, участники и звонки Остались вопросы? Напишите в [чат поддержки](https://t.me/kinescope_bot) — специалисты помогут!