Интеграция с Супераппом

В документе описана настройка интеграции Почты VK WorkSpace версии не ниже 1.18 и Супераппа VK WorkSpace версии не ниже 24.1.

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

Для настройки интеграции Почты и Супераппа VK WorkSpace вам потребуется:

1. Доступ к веб-интерфейсу установщика Почты VK WorkSpace

   http://<адрес_сервера_Почты_VK_WorkSpace>:8888.

2. Доступ к виртуальной машине, на которой установлен Суперапп VK WorkSpace.

1. В списке контактов в Мессенджере найдите @Metabot.

2. Отправьте в чат сообщение /start.

3. Нажмите Создать нового бота.

4. Введите ник для нового бота. Он должен заканчиваться на bot, например vkcalendarbot.

5. Сохраните полученные ID и токен.

6. Разрешите боту отправлять сообщение первым, выполнив на сервере Супераппа VK WorkSpace команду:

    
   echo "row_add bots_can_write_first <botID>" | nc stdb.vkteams.svc.cluster.local. 4020

   где — ID созданного бота для календаря.

   В случае распределенной инсталляции выполните команду на сервере в состоянии main. Найти такой сервер можно при помощи команды ic map stdb на любом сервере.

1. Используя чат с @Metabot, создайте почтовый бот mailbot по аналогии с ботом для календаря.

2. Сохраните его ID и токен.

3. Разрешите боту отправлять сообщение первым, выполнив на сервере Супераппа VK WorkSpace команды:

    
   echo "row_add bots_can_write_first <botID>" | nc stdb.vkteams.svc.cluster.local. 4020

   где — ID созданного почтового бота.

4. Разрешите боту отправлять DeepLink:

   1. На сервере Супераппа VK WorkSpace проверьте наличие таблицы:

       
      echo "table_get bots_can_send_deeplink" | nc stdb.vkteams.svc.cluster.local. 4020

      Если таблицы нет, создайте ее:

       
      echo "stdb_table_add bots_can_send_deeplink sn@string" | nc stdb.vkteams.svc.cluster.local. 4020

   2. Добавьте бота в таблицу:

       
      echo "row_add bots_can_send_deeplink <botId>" | nc stdb.vkteams.svc.cluster.local. 4020

      где — ID созданного почтового бота.

1. Перейдите в веб-интерфейс установщика VK WorkSpace по адресу http://server-ip-address:8888.

2. На главной странице установщика перейдите в Проекты → vkteams.

3. В окне Формы проекта vkteams выберите prismtokens. Нажмите кнопку + Добавить.

   

4. Активируйте переключатель AKES (Advanced Key Encryption Setting) и заполните поля:

   

   • Разрешенные IP адреса — добавьте IP-адреса или диапазоны (CIDR) гипервизоров-фронтов Почты;
   • Токен — укажите произвольную строку-токен;
   • Разрешенные методы API — добавьте API методы;
   • Имя токена — укажите наименование токена.

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

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

7. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером static-prismtokens-init1 нажмите на шестеренку:

   

8. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

1. На главной странице установщика перейдите в Проекты → vkteams.
2. В окне Формы проекта vkteams выберите apigw.
3. В поле admin_allow_list добавьте необходимые IP-адреса.
4. Нажмите кнопку Сохранить настройки.
5. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
6. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером apigwv21 нажмите на шестеренку:
7. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

1. На главной странице установщика перейдите в Проекты → vkteams.

2. В окне Формы проекта vkteams выберите nomail.

3. В поле Права доступа к myteam admin (myteam_admin) укажите CN нужной группы администраторов. По умолчанию в поле указано значение *.

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

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

6. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером nomail1 нажмите на шестеренку:

7. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

8. Проверьте настройку командой:

    
   kubectl -n vkteams exec -it nomail-a-1 -c nomail-tarantool -- tarantoolctl connect 3301 <<< "cfg.otp_permission.apps"

1. Получите значения adminSn и adminRid учетной записи администратора, выполнив команду:

    
   echo "show admin@admin.qdit" | nc prof-st.vkteams.svc.cluster.local 4020

2. На главной странице установщика перейдите в Проекты → vkteams.

3. В окне Формы проекта vkteams выберите mail_integrations.

4. В полях rid пользователя admin и SN пользователя admin укажите значения, полученные в п.1 текущего шага.

5. Если включена интеграция с почтой по BGP (ws_interop), в поле Домен внутренней почты укажите необходимый домен. Если интеграция по BGP не используется, оставьте значение по умолчанию.

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

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

8. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером myteam-admin1 нажмите на шестеренку:

9. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

10. Проверьте изменения командой:

     
    kubectl -n vkteams exec -it $(kubectl -n vkteams get po -l app=myteam-admin | sed 1d | awk '{print $1}') -c myteam-admin -- cat /usr/local/etc/godmod/godmod.yaml

1. На главной странице установщика перейдите в Проекты → vkteams.
2. В окне Формы проекта vkteams выберите apigw.
3. В поле admin_allow_list добавьте необходимые IP-адреса.
4. Нажмите кнопку Сохранить настройки.
5. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
6. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером apigwv21 нажмите на шестеренку:
7. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

1. На главной странице установщика перейдите в Проекты → vkteams.
2. В окне Формы проекта vkteams выберите apigw.
3. В поле admin_allow_list добавьте необходимые IP-адреса.
4. Нажмите кнопку Сохранить настройки.
5. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
6. Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером apigwv21 нажмите на шестеренку:
7. В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

1. На главной странице установщика перейдите в Проекты → vkteams.
2. В окне Формы проекта vkteams выберите mail_integrations.
3. Активируйте переключатель Включить мини-аппы Почты, Календаря и Диска.
4. Нажмите кнопку Сохранить настройки.

1. Получите access_token. Подключитесь по SSH к серверу Почты VK WorkSpace (к машине, где запущен onpremise-depoyer_linux в случае распределенной установки) и выполните команду:

    
   grep -i webapi_vkt_token /home/deployer/main.yaml

2. На главной странице установщика перейдите в Проекты → vkteams.

3. В окне Формы проекта vkteams выберите skywalker_cloud.

4. Активируйте переключатель Включить сохранение в облако и заполните поля:

   • access_token — укажите полученное значение access_token;
   • timeout — при необходимости измените значение таймаута.

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

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

7. Разверните раздел Мессенджер VK WorkSpace. Перезапустите по очереди контейнеры myteam-config-json1, myteam-admin1, files1 и skywalker1: в строке с каждым контейнером нажмите на шестеренку и в открывшемся окне — кнопку Запустить.

Все описанные ниже действия выполняются в веб-интерфейсе установщика Почты VK WorkSpace:

http://<адрес_сервера_Почты_VK_WorkSpace>:8888

Если при первичной установке Почты VK WorkSpace не были включены компоненты интеграции с Супераппом VK WorkSpace, их необходимо включить.

1. Нажмите на кнопку в правом верхнем углу, выберите пункт Продукты.
2. Перейдите на вкладку Администрирование, включите компоненты Интеграция Почты с мессенджером VK WorkSpace и Двухфакторная аутентификация и нажмите кнопку Сохранить.
3. Перейдите на вкладку Почта, включите компоненты Бот календаря для мессенджера VK WorkSpace и Бот новых почтовых сообщений для мессенджера VK WorkSpace и нажмите кнопку Сохранить.
4. Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
5. Нажмите кнопку Добавить и выберите Несколько контейнеров.
6. На открывшейся форме выберите роли для добавления. В колонке Установлено примените фильтр не более 0, выберите гипервизоры и режим генерации — На одном из гипервизоров или На каждом гипервизоре — и нажмите кнопку Добавить.

1. На главной странице установщика перейдите в Настройки → Интеграции.

2. Выберите вкладку Интеграция Почты с мессенджером VK WorkSpace.

3. Войдите в режим редактирования, нажав иконку .

4. Включите компонент Использовать SSL-шифрование для межсерверных запросов.

5. Заполните поля:

   Название поля	Значение
   Адрес API VK Teams для добавления/удаления пользователей	stentor.<домен Супераппа VK WorkSpace>.ru
   Адрес API управления VK Teams	admin.<домен Супераппа VK WorkSpace>
   Токен API управления VK Teams	Нажмите на серую кнопку в поле, чтобы сгенерировать токен
   Адрес API бинарных данных VK Teams	ub.<домен Супераппа VK WorkSpace>
   Адрес клиентского API VK Teams	u.<домен Супераппа VK WorkSpace>
   Адрес веб-версии VK Teams	webim.<домен Супераппа VK WorkSpace>
   Адрес Mini App API	files-n.<домен Супераппа VK WorkSpace>
   Адрес API звонков (ссылок на звонок)	call.<домен Супераппа VK WorkSpace>
   Адрес сервера документации VK Teams	Укажите адрес портала организации, по которому доступно клиентское приложение Супераппа VK WorkSpace и инструкции к нему, например: dl.<домен>
   Адрес сервера VK Teams, где находится Grafana	Для версии Супераппа VK WorkSpace 24.2 и ниже: stentor.<домен Супераппа VK WorkSpace>/myteam-grafana. Для версий Супераппа VK WorkSpace 24.3 и 24.9: stentor.<домен Супераппа VK WorkSpace>/grafana. Начиная с версии Супераппа VK WorkSpace 25.2: stentor.<домен Супераппа VK WorkSpace>/dashboards
   Путь URL-адреса для Grafana в домене панели администрирования	myteam-grafana
   Токен VK Teams для получения структуры организаций в панели администрирования	Значение key из шага 3 «Создайте токен biz-admin»
   Пользователь ClickHouse VK Teams	biz
   Пароль пользователя ClickHouse VK Teams	Чтобы получить пароль, выполните команду на машине с установщиком: cat /home/deployer/secrets/vkteams/secrets.yaml | grep clickhouse_metrics_biz_password -A 1
   Домен Keycloak VK Teams для двухфакторной авторизации	di.<домен Keycloak VK WorkSpace>
   Токен VK Teams для получения списка активных сессий (2fa)	Полный prism-token вида otp_bot_<секрет>. Создайте токен по аналогии с шагом 3 «Создайте токен biz-admin», указав имя токена otp_bot и метод session/listUser
   Домен Keycloak VK Teams для двухфакторной авторизации	di.<домен Keycloak VK WorkSpace>
   Токен VK Teams для получения списка активных сессий (2fa)	Полный prism-token вида otp_bot_<секрет>. Создайте токен по аналогии с шагом 3 «Создайте токен biz-admin», указав имя токена otp_bot и метод session/listUser
   Список IP адресов/подсетей VK Teams (для ACL в SWA)	<IP-адрес сервера Супераппа VK WorkSpace>

   

6. При необходимости включите компонент VK Teams поддерживает внешнюю авторизацию.

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

1. На главной странице установщика перейдите в Настройки → Доменные имена.

2. Нажмите на кнопку Добавить сертификат под заголовком SSL-сертификаты.

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

   -----BEGIN CERTIFICATE----- и -----END CERTIFICATE----- и -----BEGIN PRIVATE KEY----- и -----END PRIVATE KEY-----.

4. Кликните по кнопке Сохранить:

   

Есть второй вариант:

1. Нажмите на кнопку Выбрать файл.
2. Укажите путь к файлу с сертификатом .crt.
3. Укажите путь к файлу с ключом .key.
4. Кликните по кнопке Сохранить.

1. Перейдите в Настройки → Интеграции.

2. Выберите вкладку Боты для VK Teams.

3. Перейдите в режим редактирования, нажав иконку .

4. Заполните поля:

   Название поля	Значение
   Адрес bot-api VK Teams	api.<домен>
   ID бота календаря VK Teams	ID бота, созданного на шаге 1 «Создайте бот для календаря»
   Токен бота календаря VK Teams	Токен бота, созданного на шаге 1 «Создайте бот для календаря»
   Токен бота OTP VK Teams (2fa)	Токен OTP-бота, созданного по аналогии с шагом 1 «Создайте бот для календаря» (имя — otpbot)
   Токен бота новых почтовых сообщений VK Teams	Токен бота, созданного на шаге 2 «Создайте почтовый бот»

   

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

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

Требования описаны в инструкции Администрирование Доски VK WorkSpace.

Если все требования выполнены, то Доска сама появится в десктопном приложении Супераппа.

Технический писатель: Белова Ирина