Настройка интеграции Супераппа и Почты VK WorkSpace

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

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

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

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

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

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

http://<адрес_сервера_Почты_VK_WorkSpace>:8888.
Доступ к виртуальной машине, на которой установлен Суперапп VK WorkSpace.

Внимание

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

Настройки на стороне Супераппа VK WorkSpace

Внимание

Все команды в консоли выполняются под пользователем root.

Шаг 1. Создайте бот для календаря

В списке контактов в Мессенджере найдите @Metabot.
Отправьте в чат сообщение /start.
Нажмите Создать нового бота.
Введите ник для нового бота. Он должен заканчиваться на bot, например vkcalendarbot.
Сохраните полученные ID и токен.
Разрешите боту отправлять сообщение первым, выполнив на сервере Супераппа VK WorkSpace команду:
```
echo "row_add bots_can_write_first <botID>" | nc stdb.vkteams.svc.cluster.local. 4020
```
где <botID> — ID созданного бота для календаря.

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

Шаг 2. Создайте почтовый бот

Используя чат с @Metabot, создайте почтовый бот mailbot по аналогии с ботом для календаря.
Сохраните его ID и токен.
Разрешите боту отправлять сообщение первым, выполнив на сервере Супераппа VK WorkSpace команды:
```
echo "row_add bots_can_write_first <botID>" | nc stdb.vkteams.svc.cluster.local. 4020
```
где <botID> — ID созданного почтового бота.
Разрешите боту отправлять 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
```
  где <botID> — ID созданного почтового бота.

Шаг 3. Создайте токен biz-admin

Перейдите в веб-интерфейс установщика VK WorkSpace по адресу http://server-ip-address:8888.
На главной странице установщика перейдите в Проекты → vkteams.
В окне Формы проекта vkteams выберите prismtokens. Нажмите кнопку + Добавить.
Активируйте переключатель AKES (Advanced Key Encryption Setting) и заполните поля:
- Разрешенные IP адреса — добавьте IP-адреса или диапазоны (CIDR) гипервизоров-фронтов Почты;
- Токен — укажите произвольную строку-токен;
- Разрешенные методы API — добавьте API методы;
- Имя токена — укажите наименование токена.
Нажмите кнопку Сохранить настройки.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером static-prismtokens-init1 нажмите на шестеренку:
В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

Шаг 4. Откройте доступ в окружение администратора

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

Шаг 5. Добавьте CN-группы администраторов

На главной странице установщика перейдите в Проекты → vkteams.
В окне Формы проекта vkteams выберите nomail.
В поле Права доступа к myteam admin (myteam_admin) укажите CN нужной группы администраторов. По умолчанию в поле указано значение *.
Нажмите кнопку Сохранить настройки.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером nomail1 нажмите на шестеренку:
В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

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

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

Шаг 6. Получите adminSn и adminRid и настройте mpop

Получите значения adminSn и adminRid учетной записи администратора, выполнив команду:
```
echo "show admin@admin.qdit" | nc prof-st.vkteams.svc.cluster.local 4020
```
На главной странице установщика перейдите в Проекты → vkteams.
В окне Формы проекта vkteams выберите mail_integrations.
В полях rid пользователя admin и SN пользователя admin укажите значения, полученные в п.1 текущего шага.
Если включена интеграция с почтой по BGP (ws_interop), в поле Домен внутренней почты укажите необходимый домен. Если интеграция по BGP не используется, оставьте значение по умолчанию.
Нажмите кнопку Сохранить настройки.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Разверните раздел Мессенджер VK WorkSpace. В строке с контейнером myteam-admin1 нажмите на шестеренку:
В открывшемся окне нажмите кнопку Запустить для перезапуска выбранного контейнера.

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

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

Шаг 7. Настройте сервис Stentor

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

Шаг 8. Настройте CORS

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

Шаг 9. Настройте отображение сервисов в клиентском приложении Супераппа VK WorkSpace

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

Примечание

Переключение между несколькими доменами ($switch-domain) в on-premise версии не используется. Если эта функциональность необходима, на машине с установщиком VK WorkSpace отредактируйте файл projects/vkteams/helm-releases/myteam-config-json/custom_values.yaml, внеся нужные настройки. Затем перезапустите установщик, а после — в веб-интерфейсе перезапустите сначала контейнер myteam-config-json1, затем myteam-admin1.

Шаг 10. Настройте сервис Skywalker

Примечание

Этот шаг выполняется, если используется Диск VK WorkSpace.

Получите access_token. Подключитесь по SSH к серверу Почты VK WorkSpace (к машине, где запущен onpremise-depoyer_linux в случае распределенной установки) и выполните команду:
```
grep -i webapi_vkt_token /home/deployer/main.yaml
```
Примечание

В команде используется директория /home/deployer/. Но если при установке Почты вы распаковали архив с дистрибутивом в другую директорию, укажите ее в команде.
На главной странице установщика перейдите в Проекты → vkteams.
В окне Формы проекта vkteams выберите skywalker_cloud.
Активируйте переключатель Включить сохранение в облако и заполните поля:
- access_token — укажите полученное значение access_token;
- timeout — при необходимости измените значение таймаута.
Нажмите кнопку Сохранить настройки.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Разверните раздел Мессенджер VK WorkSpace. Перезапустите по очереди контейнеры myteam-config-json1, myteam-admin1, files1 и skywalker1: в строке с каждым контейнером нажмите на шестеренку и в открывшемся окне — кнопку Запустить.

Настройки на стороне Почты VK WorkSpace

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

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

Шаг 1. Включите интеграцию с Супераппом VK WorkSpace

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

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

Шаг 2. Укажите настройки интеграции веб-интерфейсе установщика Почты

В веб-интерфейсе установщика перейдите на вкладку Настройки.
Выберите Интеграции→ Интеграция с VK Teams.
Включите флаг Использовать SSL шифрование.

Заполните все поля:

Название поля	Значение
Адрес API VK Teams для добавления/удаления пользователей	stentor.<домен Супераппа VK WorkSpace>.ru
Адрес API управления VK Teams	admin.<домен Супераппа VK WorkSpace>
Адрес 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 /usr/local/etc/k8s/helmwave/projects/godmod/secrets/clickhouse-metric-cluster.yml \| grep password: \| cut -d':' -f2 \| sed 's/ //'`
Список IP адресов/подсетей VK Teams (для ACL в SWA)	<IP-адрес сервера Супераппа VK WorkSpace>

Примечание

На скриншоте ниже в качестве домена Супераппа VK WorkSpace используется vkt-02.on-premise.ru. Используйте ваш домен Супераппа VK WorkSpace.

Шаг 3. Импортируйте сертификаты

Внимание

Этот шаг необходимо выполнить, если вы используете свой центр сертификаци.

Подключение к компонентам Супераппа VK WorkSpace происходит по SSL, поэтому может возникать ошибка с недоверием к сертификату. Поскольку проверка SSL происходит при развертывании контейнеров calendarbot, то установить их вручную нельзя. Ошибка недоверия сертификатов происходит и для контейнеров mailbot, mailapi, calendarapi.

Чтобы избежать проблем с сертификатами выполните следующие действия:

Подключитесь к виртуальным машинам-фронтам, на которых развернуты контейнеры calendarbot-api*, calendarbot-processor*, mailbot*, mailapi*, calendarapi*.

Создайте директории certs для контейнеров:

mkdir /opt/mailOnPremise/dockerVolumes/calendarbot-api1/certs 
mkdir /opt/mailOnPremise/dockerVolumes/calendarbot-processor1/certs 
mkdir /opt/mailOnPremise/dockerVolumes/mailbot1/certs 
mkdir /opt/mailOnPremise/dockerVolumes/mailapi1/certs 
mkdir /opt/mailOnPremise/dockerVolumes/calendarapi1/certs

Скопируйте подготовленные заранее выпускающий и корневой сертификаты (только в формате .crt):

cp <your_cert.crt> /opt/mailOnPremise/dockerVolumes/calendarbot-api<номер_контейнера>/certs/
cp <your_cert.crt> /opt/mailOnPremise/dockerVolumes/calendarbot-processor<номер_контейнера>/certs/
cp <your_cert.crt> /opt/mailOnPremise/dockerVolumes/mailbot<номер_контейнера>/certs/
cp <your_cert.crt> /opt/mailOnPremise/dockerVolumes/mailapi<номер_контейнера>/certs/
cp <your_cert.crt> /opt/mailOnPremise/dockerVolumes/calendarapi<номер_контейнера>/certs/

Создайте файл custom_roles.yaml:
```
nano /home/deployer/custom_roles.yaml
```

Добавьте в файл:

Внимание

Перечень команд нужно передавать с помощью командного интерпретатора bash -с, иначе контейнер упадет.

calendarbot-api:
  volumes:
    - src: etc
      dst: /usr/local/etc
    - src: certs
      dst: /etc/pki/ca-trust/source/anchors
  command: bash -c "update-ca-trust extract && /usr/local/bin/calendarbot_api --config /usr/local/etc/calendar-bot-api.yaml"

calendarbot-processor:
  volumes:
    - src: etc
      dst: /usr/local/etc
    - src: certs
      dst: /etc/pki/ca-trust/source/anchors
  command: bash -c "update-ca-trust extract && /usr/local/bin/calendarbot_processor --config /usr/local/etc/calendar-bot-processor.yaml"

mailbot:
  volumes:
    - src: conf
      dst: /usr/local/etc/
    - src: certs
      dst: /etc/pki/ca-trust/source/anchors
  entrypoint: bash -c 'update-ca-trust extract; exec /usr/local/bin/mailbot -config /usr/local/etc/mailbot.yaml -log /dev/stdout'

mailapi:
  volumes:
    - src: conf
      dst: /usr/local/etc
    - src: tmp
      dst: /tmp
    - src: log
      dst: /var/log
    - src: aestat
      dst: /var/log/aestat
    - src: static
      dst: /usr/local/www
    - src: entrypoint
      dst: /entrypoint.d
    - src: certs
      dst: /etc/pki/ca-trust/source/anchors
  command: bash -c "update-ca-trust extract && /entrypoint.d/mailapi.sh" 

calendarapi:
  volumes:
    - src: etc
      dst: /usr/local/etc
    - src: entrypoint
      dst: /entrypoint.d
    - src: certs
      dst: /etc/pki/ca-trust/source/anchors

В контейнере calendarapi, в файл /home/deployer/configs/calendar/calendarapi.sh добавьте команду для обновления сертификата:
```
update-ca-trust extract || true
```
Итоговый вид файла:
```
#!/bin/bash

export WAITING_DB_MYSQL=""
export WAITING_DB_PGSQL="calendarpg"

source /entrypoint.d/waiting_dbs.sh

update-ca-trust extract || true

exec $@
```
Перезапустите установщик:
```
sudo systemctl restart deployer.service
```
Остановите и удалите контейнеры calendarapi-envoy*:
```
docker stop calendarapi-envoy1
docker rm calendarapi-envoy1
```
Выполните шаг up_container в веб-интерфейсе установщика, для контейнеров: calendarbot-api*, calendarbot-processor*, mailbot*, mailapi*, calendarapi*.
Запустите автоматическую установку.

Шаг 4. Заполните данные ботов в веб-интерфейсе установщика Почты

В веб-интерфейсе установщика перейдите на вкладку Настройки.
Выберите Интеграции → Боты для VK Teams.
Включите флаг Использовать SSL-шифрование.

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

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

Примечание

На скриншоте ниже используется адрес bot-api Супераппа VK WorkSpace с тестового стенда. Используйте ваш адрес bot-api Супераппа VK WorkSpace.

Шаг 5. Завершите настройку

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