Авторизация от имени сотрудника

Настройка авторизации

Авторизация от имени сотрудника и страница бота в витрине настраиваются на вкладке OAuth в карточке бота. Менять их могут создатель бота и администраторы пространства, если бот открыт им для редактирования — подробнее в разделе Настройки бота.

Одной вкладки OAuth для авторизации мало: сотрудник должен суметь написать боту, а бот — узнать о сообщении и ответить кнопкой. Всё, что должно быть включено у бота, собрано в Чек-листе запуска.

Включение

Откройте бота на вкладке Управление в разделе Интеграции > Боты и перейдите на вкладку OAuth. Пока авторизация выключена, на ней одна карточка с кнопкой Включить.

Вкладка «OAuth» до включения авторизации

Нажмите Включить: откроется окно Включение авторизации с тремя полями.

Окно «Включение авторизации»

Где хранится секрет — от этого зависит, как бот обменивает код авторизации на токен:

Серверное, с секретом — код обменивает ваш сервер, а client_secret хранится только на нём. Подходит боту, у которого есть свой бэкенд.
Браузер, мобильное, CLI — секрета нет, код обменивается по PKCE. Подходит приложению, которое работает на устройстве сотрудника и не может спрятать секрет.

Адреса возврата (поле Redirect URI) — куда браузер вернёт сотрудника после согласия, каждый адрес с новой строки. Правила:

HTTPS обязателен для всех адресов, кроме адресов на этом же компьютере: localhost, 127.0.0.1 и [::1].
Адрес в ссылке авторизации должен совпадать с одним из списка точно. Параметры запроса при сравнении не учитываются, а у адресов на этом же компьютере — ещё и порт: приложению на компьютере сотрудника подойдёт любой свободный.
Нужен хотя бы один адрес.

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

Нажмите Включить в окне. У серверного приложения сразу откроется окно Авторизация включена с client_id и client_secret: секрет показывается один раз, скопируйте его кнопкой Скопировать и закрыть.

Идентификатор и секрет

Вкладка «OAuth» в карточке бота

После включения на вкладке видны client_id и замаскированный client_secret. client_id не секретный: он входит в ссылку авторизации.

Если секрет утёк, нажмите значок обновления рядом с client_secret и подтвердите Обновить секрет. Старое значение перестанет работать сразу, поэтому сначала подготовьте бота к замене. Уже выданные авторизации и полученные токены продолжат работать, новое значение показывается один раз.

Настройку Где хранится секрет можно поменять позже. При переходе на вариант Серверное, с секретом client_secret показывается один раз, как при включении.

Адреса возврата меняются в поле Redirect URI на той же карточке: поправьте список и нажмите Сохранить под полем.

Запрашиваемый доступ

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

Блок «Запрашиваемый доступ»

Набор один на бота. Параметр scope в ссылке авторизации ни на что не влияет: сервер всегда подставляет набор из настроек.
В набор можно включить только права, доступные самому боту. Права, которые выдаются лишь персональным токенам, запросить нельзя.
Права каждой авторизации дополнительно ограничены ролью сотрудника: право, недоступное его роли, работать не будет.
Изменение набора не меняет уже выданные авторизации. Добавленные права сотрудник подтвердит при следующей авторизации, а убранные останутся в выданных токенах, пока сотрудник не отзовёт доступ или авторизацию у бота не отключат.

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

Страница на витрине

Блок Страница на витрине на этой же вкладке публикует бота в витрине: в нём описание и скриншоты для страницы бота и переключатель Опубликовать в витрине. Как заполнить страницу и опубликовать бота — в разделе Как опубликовать бота.

Отключение

Блок Удаление OAuth-клиента внизу вкладки отключает авторизацию у бота.

Блок «Удаление OAuth-клиента»

После подтверждения:

все авторизации, выданные сотрудниками, отзываются: токены сотрудников у бота перестают работать, и следующий запрос с ними вернёт 401;
бот пропадает из витрины, а описание и скриншоты удаляются без возможности вернуть;
новые авторизации с этим client_id не проходят.

Собственные токены бота продолжают работать. Если авторизацию включить снова, у бота будут прежние client_id и client_secret, если секрет не обновляли, а в витрину бот вернётся только после новой публикации.

Через API

Те же настройки задаются методом PUTРедактирование бота или сразу при создании методом POSTНовый бот:

На вкладке	В API
Включить и Где хранится секрет	`oauth_client.confidential`: `true` — серверное, с секретом, `false` — браузер, мобильное, CLI
Адреса возврата	`oauth_client.redirect_uris`
Запрашиваемый доступ	`oauth_client.scopes`
Страница на витрине	`promo.published`, `promo.description` и `promo.promo_images`
Удаление OAuth-клиента	`oauth_client: null`

Объект oauth_client включает авторизацию, если она выключена, и меняет её настройки, если включена. Права для набора берут из GETКаталога прав бота. У серверного приложения client_secret приходит в ответе один раз: при включении и при переходе на вариант с секретом. Новый секрет выпускает метод POSTРотация секрета клиента.

Включена ли авторизация, показывает поле oauth_client_enabled в объекте бота: параметры в oauth_client могут прийти и у бота с выключенной авторизацией.

Скриншоты для витрины загружают так же, как вложения сообщений, методом POSTПолучение подписи, ключа и других параметров, а их key передают в promo.promo_images.