Инструкция по настройке SSO-аутентификации при помощи утилиты SSO-CLI

Назначение документа

Если в инсталляции нет Панели администратора VK WorkSpace, вы можете настроить SSO-аутентификацию в Мессенджер и ВКС при помощи утилиты SSO-CLI. SSO-аутентификация будет выполняться при помощи сервиса Stroma в составе Мессенджер и ВКС. Данная функциональность доступна для версии Мессенджер и ВКС 25.2.1 и выше.

Документ предназначен для использования администраторами организации.

Дополнительная документация

Архитектура и описание системы — в документе представлена информация о сервисах Мессенджер и ВКС, обеспечивающих функциональность SSO-аутентификации, а также расположение log-файлов данных сервисов. Не является частью публичной документации, обратитесь к представителю VK Tech, чтобы ознакомиться с документом.

Инструкция по настройке SSO-аутентификации (Stroma, SWA) — в документе описана настройка SSO-аутентификации по протоколу OpenID Connect (OIDC) в Мессенджер и ВКС и Почте VK WorkSpace при помощи сервиса Stroma в составе Мессенджер и ВКС.

Предварительные условия для настройки SSO аутентификации

Клиентские платформы в рамках запроса аутентификации должны поддерживать аутентификацию через внешнего провайдера аутентификации, в результате которой сервер отдаст ответ, содержащий email и atoken (ключ, необходимый для инициализации сессии и получения идентификатора сессии — aimsid), используемые далее при старте сессии мессенджера.

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

Для настройки SSO-аутентификации необходимо:

Наличие провайдера аутентификации.
Доступ к серверу Мессенджер и ВКС.

Способ 1

Создайте в любой удобной для вас директории файл с названием config.yaml и следующими параметрами (значения параметров приведены в качестве примера):
```
type: <KK>
service_title: <Keycloak>
service_description: <Our Keycloak>
auth_uri: <http://185.241.192.178:8080/realms/sso/protocol/openid-connect/auth>
userinfo_uri: <http://185.241.192.178:8080/realms/sso/protocol/openid-connect/userinfo>
token_uri: <http://185.241.192.178:8080/realms/sso/protocol/openid-connect/token>
introspection_uri: <http://185.241.192.178:8080/realms/sso/protocol/openid-connect/token/introspect
client_id: <client id>
client_secret: <client secret>
domains: [example.com, example.org]
```
где:
- type — тип IDP-провайдера (например ADFS или Keycloak).
- service_title — название IDP-провайдера.
- service_description — краткое описание IDP-провайдера.
- auth_uri — authorization endpoint, полученный из настроек IDP.
- userinfo_uri — user info endpoint, полученный из настроек IDP.
- token_uri — token endpoint, полученный из настроек IDP.
- introspection_uri — introspection endpoint, полученный из настроек IDP. Необязательный параметр.
- client_id — clientID, полученный из настроек IDP.
- client_secret — clientSecret, полученный из настроек IDP.
- domains — через запятую укажите домены, для которых подключается SSO-аутентификация.
Выполните в консоли команду:
```
sso setup <путь до config.yaml>
```

Способ 2

Выполните в консоли команду:

sso setup

и следуйте инструкциям в консоли.

Способ 3

Создайте IDP-провайдера при помощи команды:
```
sso provider create
```
Подключите IDP-провайдера к домену:
```
sso connect <domain> <provider_id>
```
где:
- domain — домен, для которого подключается SSO-аутентификация.
- provider_id — идентификатор IDP-провайдера, полученный на предыдущем шаге.
Включите SSO-аутентификацию:
```
sso enable_sso <domain>
```
где domain — домен, для которого подключается SSO-аутентификация.

Команды утилиты

setup <путь до config.yaml> — настраивает SSO-аутентификацию одной командой. Если не указан путь к конфигурационному файлу, следуйте инструкциям в консоли.

connect <domain> <provider_id> — создает связку домена и IDP-провайдера для механизма SSO-аутентификации.

disconnect <domain> <provider_id> — убирает связку домена и IDP-провайдера в рамках механизма SSO-аутентификации.

provider create <путь до config.yaml> — добавляет конфигурацию провайдера. Если не указан путь к конфигурационному файлу, следуйте инструкциям в консоли.

provider delete <provider_id> — удаляет конфигурацию IDP-провайдера.

provider edit <путь до config.yaml> — изменяет конфигурацию IDP-провайдера. Если не указан путь к конфигурационному файлу, следуйте инструкциям в консоли.

provider get <provider_id> — позволяет получить текущую конфигурацию IDP-провайдера.

provider list — позволяет получить информацию по всем IDP-системам.

token <target_id> — формирует секрет для мини-аппа.

disable_sso <domain> — выключает SSO-аутентификации на домене.

enable_sso <domain> — включает SSO-аутентификации на домене.

webhook add [target_id] — добавляет вебхук. По умолчанию, target_id = messenger.

webhook delete [target_id] — удаляет все вебхуки по target_id. По умолчанию, target_id = messenger.

webhook get [target_id] — позволяет получить информацию о вебхуке. По умолчанию, target_id = messenger.

help — помощь по любой команде.