Инструкция по настройке SSO-аутентификации (Stroma, SWA)

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

В документе описана настройка SSO-аутентификации по протоколу OpenID Connect (OIDC) в Мессенджере и Почте VK WorkSpace при помощи сервиса Stroma в составе Мессенджера. Данная функциональность доступна для версии Почты и Мессенджера 25.2.1 и выше.

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

Предварительные условия

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

1. Наличие провайдера аутентификации, поддерживающего протокол OIDC.
2. Доступ к серверу Мессенджер и ВКС.
3. Доступ к серверу Почты VK WorkSpace при наличии.
4. Доступ к веб-интерфейсу установщика VK Workspace.
5. Доступ к Панели администратора VK WorkSpace при наличии.

Шаг 1. Настройка параметров авторизации в веб-интерфейсе установщика VK Workspace

1. В веб-интерфейсе установщика VK Workspace перейдите в Проекты → vkteams.
2. В окне Формы проекта vkteams выберите Auth (Авторизация). Откроется форма с параметрами для заполнения:
3. Заполните параметры формы в соответствии с таблицей.

   Параметр	Рекомендуемое действие	Примечание
   Вход через SSO (сервис stroma)	Включить	Включает SSO через сервис Stroma
   Ключ подписи miniapp-токенов	Заполнить произвольной строкой	Ключ для подписи
   Ключ подписи одноразовых токенов	Заполнить произвольной строкой	Ключ для подписи
   Ключ подписи silent-токенов	Заполнить произвольной строкой	Ключ для подписи
   Stroma SSO домен	Указать домен	Должен соответствовать вашему домену
   Ключ подписи JWT	Заполнить произвольной строкой	Ключ для подписи
   Stroma user_management (stentor, biz)	Выбрать biz или stentor	biz — если есть Панель администратора, иначе stentor

4. Нажмите кнопку Сохранить настройки.
5. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
6. Запустите автоматическую установку, нажав на кнопку Play .

Шаг 2. Настройка сквозной авторизации для почтовых миниаппов

Примечание

Данный шаг выполняется, если в установщике есть Почта VK WorkSpace и вы хотите настроить для нее сквозную авторизацию в приложении VK WorkSpace. Если в установщике нет Почты, пропустите этот шаг.

1. На сервере Мессенджер и ВКС выполните команду:

   sso token swa
   

   Сохраните полученное значение.

2. В веб-интерфейсе установщика VK WorkSpace перейдите в Настройки → Переменные окружения.

3. На панели слева нажмите gofau.

   

4. Нажмите кнопку Редактировать , затем кнопку Добавить.

5. Добавьте переменную GOFAU_IDM_CLIENT_SECRET со значением из пункта 1.

   

6. Нажмите кнопку Сохранить.

7. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.

8. Запустите автоматическую установку, нажав на кнопку Play .

Шаг 3. Настройка SSO-аутентификации

Вы можете выполнить настройку SSO-аутентификации одним из двух равноценных способов — в зависимости от того, есть ли в установщике VK WorkSpace Панель администратора:

• через Панель администратора — если Панель администратора есть;
• с помощью утилиты командной строки — если Панели администратора нет.

Настройка SSO-аутентификации через Панель администратора

Примечание

Выполняется, если в установщике VK WorkSpace есть Панель администратора.

Интеграция с Панелью администратора

1. Подключитесь к серверу Мессенджер и ВКС и сгенерируйте client_id и client_secret:

   k -n vkteams exec -it tokeeper-a-1 -- bash
   creds=$(curl -s http://stroma.vkteams.svc.cluster.local:8036/api/v1/private/generate_credentials); \
   client_id=$(echo $creds | jq -r ".client_id"); \
   client_secret=$(echo $creds | jq -r ".client_secret"); \
   client_secret_hash=$(echo $creds | jq -r ".client_secret_hash"); \
   echo "client_id: $client_id"; \
   echo "client_secret: $client_secret"; \
   echo "tokeeper.request.add_application('biz', 'biz admin', '$client_id', '$client_secret_hash', '')" | tarantoolctl connect 127.0.0.1:3301
   

   Запомните выводы команд.

2. В веб-интерфейсе установщика VK Workspace перейдите в раздел Настройки → Интеграции.

3. На панели слева нажмите Интеграция почты с мессенджером VK WorkSpace.

   

4. Нажмите кнопку Редактировать .

5. Включите переключатель VK Teams поддерживает внешнюю авторизацию.

6. В появившихся полях укажите client_id и client_secret из пункта 1.

   

7. Нажмите кнопку Сохранить.

   

8. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.

9. Запустите автоматическую установку, нажав на кнопку Play .

Настройка в Панели администратора

1. В расширенной панели /admin перейдите в раздел Фичи и подключите:
   • sso-enabled — для включения поддержки SSO.
   • tmp-new-reset-sessions — для управления сессиями пользователей через Панель администратора VK WorkSpace.
   • trust-swa — для создания пользователей.
2. В Панели администратора перейдите в Конфигурация → Настройки → SSO аутентификация.Откроется форма с параметрами для заполнения:
3. Заполните параметры формы в соответствии с таблицей.

   Параметр	Рекомендуемое действие	Примечание
   Название сервиса	Указать название IDP-провайдера	Например, Keycloak
   Описание сервиса	Заполнить кратким описанием	Необязательное поле
   URL для обратного редиректа	Заполняется автоматически	Не требует ручного ввода
   URL для корпоративной авторизации	Заполнить значением Auth URI из настроек IDP	Обязательное поле
   URL для user info	Заполнить значением Userinfo URI из настроек IDP	Обязательное поле
   URL получения токена	Заполнить значением Token URI из настроек IDP	Обязательное поле
   URL для валидации токена (introspection)	Заполнить значением Introspection URI из настроек IDP	Обязательное поле
   Client ID	Заполнить значением Client ID из настроек IDP	Обязательное поле
   Client Secret	Заполнить значением Client Secret из настроек IDP	Обязательное поле

4. Нажмите кнопку Сохранить.
5. Чтобы управлять сессиями пользователей, перейдите в раздел Мессенджер → Аккаунты.

Настройка SSO-аутентификации с помощью утилиты командной строки

Примечание

Выполняется, если в установщике VK WorkSpace нет Панели администратора.

Первичная настройка

Первичную настройку SSO-аутентификации выполните одним из двух способов:

• Способ 1 (интерактивно);
• Способ 2 (через файл config.yaml).

Способ 1. Интерактивно

1. Запустите программу настройки SSO-аутентификации под пользователем с правами администратора на сервере Мессенджер и ВКС:

   # sso setup
   

2. Укажите параметры SSO-аутентификации, следуя подсказкам в консоли:

   • 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 (comma-separated) — через запятую укажите домены, для которых подключается SSO-аутентификация.

   Пример настроек:

   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 (comma-separated): keycloak.sso-test.ru
   

   Пример вывода:

   successfully create IdentityProvider with id: 685b0b03-9e3c-40c9-a08f-181d039cc88e
   successfully connect domain keycloak.sso-test.ru with provider 685b0b03-9e3c-40c9-a08f-181d039cc88e
   successfully enable sso on domain: keycloak.sso-test.ru
   successfully setup SSO with 685b0b03-9e3c-40c9-a08f-181d039cc88e provider
   

Способ 2. Через файл config.yaml

1. Создайте в любой удобной для вас директории файл config.yaml с параметрами SSO-аутентификации, перечисленными в способе 1.

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

   sso setup <путь до config.yaml>
   

Изменение настройки

1. Получите список настроенных провайдеров:

   sso provider list
   

2. Cохраните настройки провайдера в файл:

   sso provider get <provider_id из шага 1> > provider.yml
   

3. Отредактируйте файл provider.yml, содержащий настройки провайдера.

4. Примените измененные настройки:

   sso provider edit provider.yml
   

Добавление домена для SSO-аутентификации

1. Получить список сконфигурированных провайдеров:

   sso provider list
   

2. Подключить домен к провайдеру:

   sso connect <new_domain> <provider_id, полученный из шага 1>
   

3. Включить sso на домене:

   sso enable_sso <new_domain>