Перейти к содержанию

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

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

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

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

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

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

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

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

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

Внимание

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

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

Внимание

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

Внимание

Шаги 4, 7 и 8 выполняются одинаково — через сервис apigw (поле admin_allow_list) с перезапуском контейнера apigwv21, но настраивают три разных механизма:

  • Шаг 4 — доступ в окружение администратора;
  • Шаг 7 — приложение Stentor;
  • Шаг 8 — CORS.

IP-адреса в поле admin_allow_list для разных шагов могут совпадать или различаться (например, для двух шагов из трёх адреса могут оказаться одинаковыми).

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

  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
    где <botID> — ID созданного бота для календаря.

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

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

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

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

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

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

    где <botID> — 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

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

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

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

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

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

  3. В поле admin_allow_list добавьте необходимые IP-адреса.

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

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

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

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

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

  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"

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

  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

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

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

  3. В поле admin_allow_list добавьте необходимые IP-адреса.

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

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

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

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

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

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

  3. В поле admin_allow_list добавьте необходимые IP-адреса.

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

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

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

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

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

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

  3. Активируйте переключатель Включить мини-аппы Почты, Календаря и Диска.

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

Примечание

Переключение между несколькими доменами ($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.

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

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

    Примечание

    В команде используется директория /home/deployer/. Но если при установке Почты вы распаковали архив с дистрибутивом в другую директорию, укажите ее в команде.

  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

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

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

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

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

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

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

  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
    Список IP адресов/подсетей VK Teams (для ACL в SWA) <IP-адрес сервера Супераппа VK WorkSpace>

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

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

Шаг 3. Добавьте сертификаты

Внимание

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

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

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

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

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

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

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

Примечание

Приватный ключ должен быть добавлен в открытом виде, без секретной фразы. Закодированный ключ отличается от открытого наличием слова ENCRYPTED: BEGIN ENCRYPTED PRIVATE 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. Нажмите кнопку Сохранить.

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

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

Требования для включения Доски VK WorkSpace в десктоп-приложении Супераппа

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

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