Настройка интеграции VK Teams и Почты VK WorkSpace
Назначение документа
В документе описана настройка интеграции Почты VK WorkSpace версии не ниже 1.18 и VK Teams версии не ниже 24.1.
Документ предназначен для использования администраторами организации.
Предварительные требования
Для настройки интеграции Почты и VK Teams вам потребуется:
-
Доступ к веб-интерфейсу установщика Почты VK WorkSpace
http://<адрес_сервера_Почты_VK_WorkSpace>:8888.
-
Доступ к виртуальной машине, на которой установлен VK Teams.
Внимание
Для production-систем рекомендуется производить настройки во время технологического окна.
Настройки на стороне VK Teams
Внимание
Все команды в консоли выполняются под пользователем root.
Шаг 1. Создайте бот для календаря
-
В списке контактов в VK Teams найдите @Metabot.
-
Отправьте в чат сообщение /start.
-
Нажмите Создать нового бота.
-
Введите ник для нового бота. Он должен заканчиваться на bot, например vkcalendarbot.
-
Сохраните полученные ID и токен.
-
Разрешите боту отправлять сообщение первым, выполнив на сервере VK Teams команду:
где <botID> — ID созданного бота для календаря.В случае распределенной инсталляции выполните команду на сервере в состоянии main. Найти такой сервер можно при помощи команды
ic map stdb
на любом сервере.
Шаг 2. Создайте почтовый бот
-
Используя чат с @Metabot, создайте почтовый бот mailbot по аналогии с ботом для календаря.
-
Сохраните его ID и токен.
-
Разрешите боту отправлять сообщение первым, выполнив на сервере VK Teams команды:
где <botID> — ID созданного почтового бота.
-
Разрешите боту отправлять DeepLink:
-
Зайдите на сервер VK Teams.
-
Проверьте наличие таблицы:
Если таблицы нет, создайте ее:
-
Добавьте бота в таблицу:
где <botID> — ID созданного почтового бота.
-
Шаг 3. Создайте токен biz-admin
-
Перейдите в конфигурационный файл /usr/local/etc/import_prismtokens.yaml:
-
В секции prismtokens создайте секцию biz-admin, как в примере ниже, и задайте токен в поле key:
-
Чтобы изменения вступили в силу, выполните команду:
При распределенной инсталляции VK Teams команда выполняется на одном из серверов.
Шаг 4. Откройте доступ в окружение администратора
Примечание
Этот шаг выполняется только в случае, если необходимо создание мини-аппов и управление мини-аппами.
-
Перейдите в файл конфигурации /usr/local/nginx-im/confv2/conf.d/myteam-admin_allow_hosts.inc:
-
В поле allow вместо <real.mail.ip> укажите список IP-адресов гипервизоров-фронтов Почты VK WorkSpace:
-
Чтобы изменения вступили в силу, выполните команду:
Шаг 5. Добавьте CN-группы администраторов
-
Перейдите в конфигурационный файл /usr/share/tarantool/extra_config/nomail-1/nomail-1_extra_conf.lua
-
В поле myteam-admin укажите CN-группы администраторов:
-
Чтобы изменения вступили в силу, выполните команду:
-
Проверить актуальные настройки можно командой:
Шаг 6. Создайте учетную запись с доступом в окружение администратора VK Teams
-
В любой удобной папке создайте файл users.yaml и заполните его данными учетной записи (в примере ниже это admin@admin.qdit):
users: admin@admin.qdit: email: admin@admin.qdit firstName: admin lastName: admin attributes: memberOf: ["myteam-admin"] #член группы "myteam-admin" с доступом в окружение администратора
где memberOf: — название группы пользователей с доступом в окружение администтора.
Объект users имеет тип Hash. При использовании расширенного формата yaml-файла username должен совпадать с email. В примере выше это admin@admin.qdit.
-
После создания users.yaml выполните в консоли команду:
-
Получите adminSn и adminRid созданной учетной записи:
Значения rid и sn будут в выводе команды:
Шаг 7. Отредактируйте секцию mpop в файле myteam-admin.yml
-
Перейдите в файл конфигурации myteam-admin.yml:
-
В секции mpop указажите домен Почты VK WorkSpace, sn (adminSn) и rid (adminRid), полученные на предыдущем шаге:
-
Чтобы изменения вступили в силу, поочередно выполните команды:
Для инсталляции на 1 виртуальную машину:
helm delete myteam-admin -n vkteams export HELMWAVE_USE_LOCAL_REPO_CACHE=1 helmwave up --build --tpl helmwave.yml.tpl --yml --templater gomplate -t myteam-admin
Для распределенной инсталляции VK Teams версии 23.8 и выше выполните команду на одном из первых трех серверов:
-
Для проверки изменений выполните команду:
Актуальное значение pod ID можно получить с помощью команды:
Шаг 8. Настройте сервис Stentor
-
Перейдите в конфигурационный файл /usr/local/nginx-im/confv2/conf.d/stentor.conf:
-
В поле allow вместо <real.mail.ip> укажите IP-адреса гипервизоров-фронтов Почты:
Шаг 9. Настройте CORS
-
Перейдите в конфигурационный файл /usr/local/nginx-im/confv2/nginx.conf
-
В секции map $http_origin $cors_enabled допишите:
-
В секции variables geos from hiera допишите:
# variables geos from hiera geo $realip_remote_addr $allow_biz_grafana { 127.0.0.1 1; 10.32.0.0/16 1; <real.mail.ip>/32 1; // вместо <real.mail.ip> указать IP-адреса гипервизоров-фронтов Почты VK WorkSpace default 0; }
Пример заполнения файла:
-
Чтобы изменения вступили в силу, выполните команду:
Шаг 10. Настройте отображение сервисов в клиентском приложении VK Teams
-
Перейдите в конфигурационный файл /usr/local/nginx-im/html/myteam/myteam-config.json:
-
Добавьте в секцию templates-urls:
"templates-urls": { "mail": "https://e.<домен Почты VK WorkSpace>.ru/api/v1/user/webauth/vkteams", "cloud": "https://cloud.<домен Почты VK WorkSpace>.ru", "calendar": "https://calendarx.<домен Почты VK WorkSpace>.ru", "mobile_calendar_main_url": "https://calendartouch.<домен Почты VK WorkSpace>.ru", "mobile_calendar_create_event_url": "https://calendartouch.<домен Почты VK WorkSpace>.ru/create" },
-
Добавьте в секцию mini-apps:
-
Добавьте в секцию services" – “config:
"services": { "config": { "calendar": { "external": false, "needs_auth": true, "template-domains": [ "calendarx.<домен Почты VK WorkSpace>.ru" ], "url": "https://calendarmsg.<домен Почты VK WorkSpace>.ru", "mobile-url": "https://calendartouch.<домен Почты VK WorkSpace>.ru", "mobile-create-event-url": "https://calendartouch.<домен Почты VK WorkSpace>.ru/create", "touch-web-enabled": true, "touch-web-url": "https://calendartouch.<домен Почты VK WorkSpace>.ru" }, "cloud": { "external": false, "needs_auth": true, "template-domains": [ "cloud.<домен Почты VK WorkSpace>.ru" ], "url": "https://e.<домен Почты VK WorkSpace>.ru/api/v1/user/webauth/vkteams?from=cloud¶ms=wv%3D1" }, "mail": { "external": false, "mail-android-app-urlscheme": "mail-onpremise-auth://", "mail-ios-app-urlscheme": "mailrumail-x-callback://", "mail-mobile-url": "https://e.<домен Почты VK WorkSpace>.ru/inbox", "needs_auth": true, "is-public": false, "url": "https://e.<домен Почты VK WorkSpace>.ru/inbox", // для версии Почты VK WorkSpace 1.20.2 и выше "url": "https://e.<домен Почты VK WorkSpace>.ru/api/v1/user/webauth/vkteams?wv=1" // для версии Почты VK WorkSpace 1.20 и ниже }, "orgstructure": { // добавьте эту секцию, если пользуетесь функциональностью структуры организаций "external": false, "needs_auth": true, "new": true, "url": "https://webim.<domain-vkt>/webapps/orgstructure", "url-dark": "https://webim.<domain-vkt>/webapps/orgstructure" }, } }
-
Добавьте в секцию disposition:
"disposition": { "desktop": { "leftbar": [ "tasks", "calls", "mail", "calendar", "cloud", "orgstructure" // добавьте, если пользуетесь функциональностью структуры организаций ] }, "mobile": { "services": [ "discover" ], "tabs": [ "calls", "tasks", "mail", "calendar", "orgstructure" // добавьте, если пользуетесь функциональностью структуры организаций ] } }
Шаг 11. Пересоздайте pod админ-консоли
Выполните команду:
Шаг 12. Настройте сервис Skywalker
Примечание
Этот шаг выполняется, если используется Диск VK WorkSpace.
-
Получите access_token <webapi-token>:
-
Подключитесь по SSH к серверу Почты VK WorkSpace (к машине, где запущен onpremise-depoyer_linux в случае распределенной установки).
-
Выполните команду:
Примечание
В команде используется директория /home/deployer/. Но если при установке Почты вы распаковали архив с дистрибутивом в другую директорию, укажите ее в команде.
-
-
На сервере VK Teams выполните команды:
-
В файле vim /usr/local/nginx-im/html/myteam/myteam-config.json включите флаг save-to-cloud-enabled:true.
-
Примените изменения:
-
В файле vim /usr/local/go.files.icq.com/files.icq.com.config.yaml включите флаг show_cloud_file_status: true.
-
Перезапустите службу:
-
Отредактируйте файл /usr/local/etc/skywalker-1.yaml:
cloud: host: "cloud-serverside-api.<домен_Почты>" access_token: "<webapi-token>" timeout: 60s domain: "cloud.<домен_Почты>" default_folder_to_save_file: "/Файлы мессенджера" force_loader_url: "http://cloclo-int.<домен_Почты>/dupload" mail: host: "serverside-api.<домен_Почты>" timeout: 5s log: level: "debug" async: false
-
Перезапустите службу:
-
Настройки на стороне Почты VK WorkSpace
Все описанные ниже действия выполняются в веб-интерейсе установщика Почты VK WorkSpace:
http://адрес_сервера_Почты_VK_WorkSpace:8888
Шаг 1. Включите интеграцию с VK Teams
Если при первичной установке Почты VK WorkSpace не были включены компоненты интеграции с VK Teams, их необходимо включить.
- Нажмите на кнопку в правом верхнем углу, выберите пункт Продукты.
-
Включите следующие компоненты:
- Интеграция с VK Teams.
- Календарь: бот календаря для VK Teams.
- Бот новых почтовых сообщений для VK Teams.
-
Нажмите на кнопку Сохранить.
- Перейдите на вкладку AdminPanel.
-
Сгенерируйте новые контейнеры:
- Если Почта VK WorkSpace установлена на одной машине, нажмите на кнопку Сгенерировать автоматически.
-
В случае распределенной установки:
- Нажмите Добавить → Несколько контейнеров.
- Установите фильтр Установлено не более 0.
- Распределите недостающие контейнеры по гипервизорам с учетом дублируемости.
- Нажмите на кнопку Добавить.
Шаг 2. Укажите настройки интеграции веб-интерфейсе установщика Почты
- В веб-интерфейсе установщика перейдите на вкладку Настройки.
- Выберите Интеграции → Интеграция с VK Teams.
- Включите флаг Использовать SSL шифрование.
-
Заполните все поля:
Название поля Значение Адрес API VK Teams для добавления/удаления пользователей stentor.<домен VK Teams>.ru Адрес API управления VK Teams admin.<домен VK Teams> Адрес API бинарных данных VK Teams ub.<домен VK Teams> Адрес клиентского API VK Teams u.<домен VK Teams> Адрес веб-версии VK Teams webim.<домен VK Teams> Адрес Mini App API files-n.<домен VK Teams> Адрес API звонков (ссылок на звонок) call.<домен VK Teams> Адрес сервера документации VK Teams Укажите адрес портала организации, по которому доступно клиентское приложение и инструкции VK Teams, например:
dl.<домен VK Teams>Адрес сервера VK Teams, где находится Grafana Для версии VK Teams 24.2 и ниже:
stentor.<домен VK Teams>/myteam-grafana
Начиная с версии VK Teams 24.3:
stentor.<домен VK Teams>/grafanaПуть 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 Teams> Примечание
На скриншоте ниже в качестве домена VK Teams используется vkt-02.on-premise.ru. Используйте ваш домен VK Teams.
Шаг 3. Заполните данные ботов в веб-интерфейсе установщика Почты
- В веб-интерфейсе установщика перейдите на вкладку Настройки.
- Выберите Интеграции → Боты для VK Teams.
- Включите флаг Использовать SSL-шифрование.
-
Заполните поля:
Название поля Значение Адрес bot-api VK Teams api.<домен VK Teams> ID бота календаря VK Teams ID бота, созданного на шаге 1 «Создайте бот для календаря» Токен бота календаря VK Teams token бота, созданного на шаге 1 «Создайте бот для календаря» Токен бота новых почтовых сообщений VK Teams token бота, созданного на шаге 2 «Создайте почтовый бот» Примечание
На скриншоте ниже используется адрес bot-api VK Teams с тестового стенда. Используйте ваш адрес bot-api VK Teams.
Шаг 4. Завершите настройку
- В веб-интерфейсе установщика перейдите на вкладку AdminPanel.
- Запустите автоматическую установку, нажав на кнопку Play .