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

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

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

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

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

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

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

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

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

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

Внимание

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

Настройки на стороне VK Teams

Внимание

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

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

  1. В списке контактов в VK Teams найдите @Metabot.

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

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

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

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

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

    echo "row_add bots_can_write_first <botID>" | nc 127.1 4041
    где <botID> — ID созданного бота для календаря.

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

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

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

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

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

    echo "row_add bots_can_write_first <botID>" | nc 127.1 4041

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

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

    1. Зайдите на сервер VK Teams.

    2. Проверьте наличие таблицы:

      echo "table_get bots_can_send_deeplink" | nc 127.1 4041

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

      echo "stdb_table_add bots_can_send_deeplink sn@string" | nc 127.1 4041

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

      echo "row_add bots_can_send_deeplink <botId>" | nc 127.1 4041

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

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

  1. Перейдите в конфигурационный файл /usr/local/etc/import_prismtokens.yaml:

    vim /usr/local/etc/import_prismtokens.yaml

  2. В секции prismtokens создайте секцию biz-admin, как в примере ниже, и задайте токен в поле key:

    prismtokens:
  biz-admin:
    methods:
      - _any
    ips: // список ip-адресов гипервизоров-фронтов Почты VK WorkSpace
      - 192.0.2.1 
      - 192.0.2.2 
    akes: true
    key: <your_token>

  3. Чтобы изменения вступили в силу, выполните команду:

    /usr/local/bin/import_prismtokens.py -f /usr/local/etc/import_prismtokens.yaml

    При распределенной инсталляции VK Teams команда выполняется на одном из серверов.

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

Примечание

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

  1. Перейдите в файл конфигурации /usr/local/nginx-im/confv2/conf.d/myteam-admin_allow_hosts.inc:

    vim /usr/local/nginx-im/confv2/conf.d/myteam-admin_allow_hosts.inc

  2. В поле allow вместо <real.mail.ip> укажите список IP-адресов гипервизоров-фронтов Почты VK WorkSpace:

    allow 192.0.2.1 192.0.2.2;

  3. Чтобы изменения вступили в силу, выполните команду:

    nginx.sh reload

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

  1. Перейдите в конфигурационный файл /usr/share/tarantool/extra_config/nomail-1/nomail-1_extra_conf.lua 

    vim /usr/share/tarantool/extra_config/nomail-1/nomail-1_extra_conf.lua

  2. В поле myteam-admin укажите CN-группы администраторов:

    cfg.otp_permission.apps = {
    ['myteam-client'] = '*',
    ['download_ios_application'] = '*',
    ['myteam-admin'] = {
        'myteam-admin'
    },
}

  3. Чтобы изменения вступили в силу, выполните команду:

    echo "dofile('/usr/share/tarantool/extra_config/nomail-1/nomail-1_extra_conf.lua')" | tarantoolctl enter nomail-1

  4. Проверить актуальные настройки можно командой:

    echo "cfg.otp_permission.apps" | tarantoolctl enter nomail-1

Шаг 6. Создайте учетную запись с доступом в окружение администратора VK Teams

  1. В любой удобной папке создайте файл 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.

  2. После создания users.yaml выполните в консоли команду:

    users.py --cmd add -c users.yaml

  3. Получите adminSn и adminRid созданной учетной записи:

     echo "show admin@admin.qdit" | nc 127.1 4281

    Значения rid и sn будут в выводе команды:

Шаг 7. Отредактируйте секцию mpop в файле myteam-admin.yml

  1. Перейдите в файл конфигурации myteam-admin.yml:

    cd /usr/local/etc/k8s/helmwave/
vim projects/godmod/values/myteam-admin.yml

  2. В секции mpop указажите домен Почты VK WorkSpace, sn (adminSn) и rid (adminRid), полученные на предыдущем шаге: 

    mpop:
  enable: true
  swa_host: http://swa.<домен Почты VK WorkSpace>
  swa_url: /int/CheckSession
  adminSn: admin@admin.qdit // указать значение adminSn, полученное на предыдущем шаге    
  adminRid: 0:100504  // указать значение adminRid, полученное на предыдущем шаге

  3. Чтобы изменения вступили в силу, поочередно выполните команды:

    Для инсталляции на 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 и выше выполните команду на одном из первых трех серверов:

    im_deployer --helmwave --update --hw-project godmod --hw-once

  4. Для проверки изменений выполните команду:

    kubectl exec -n vkteams -i myteam-admin-<Pod ID> -c myteam-admin -- cat /usr/local/etc/config.yaml

    Актуальное значение pod ID можно получить с помощью команды:

    kubectl get pods -A | grep myteam-admin

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

  1. Перейдите в конфигурационный файл /usr/local/nginx-im/confv2/conf.d/stentor.conf:

    vim /usr/local/nginx-im/confv2/conf.d/stentor.conf

  2. В поле allow вместо <real.mail.ip> укажите IP-адреса гипервизоров-фронтов Почты:

    location / {
    proxy_pass http://stentor_upsync$uri$is_args$args;
    allow 127.0.0.0/8;
    allow 10.32.0.0/16;
    allow <real.mail.ip>; // вместо <real.mail.ip> укажите IP-адреса гипервизоров-фронтов Почты
        deny all;
}

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

  1. Перейдите в конфигурационный файл /usr/local/nginx-im/confv2/nginx.conf

    vim /usr/local/nginx-im/confv2/nginx.conf

  2. В секции map $http_origin $cors_enabled допишите: 

    map $http_origin $cors_enabled {
    ~webim\.<домен_VK_Teams>$ 1;
    ~calendarx\.<домен_Почты>$ 1;
    ~calendarmsg\.<домен_Почты>$ 1;
    ~calendartouch\.<домен_Почты>$ 1;
    ~e\.<домен_Почты>$ 1;
    ~cloud\.<домен_для_облачных_хранилищ_Почты>$ 1;
    ~dl\.<домен_VK_Teams>$ 1;
    default 0;
}

  3. В секции 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;
    }

    Пример заполнения файла:

  4. Чтобы изменения вступили в силу, выполните команду:

    nginx.sh reload

Шаг 10. Настройте отображение сервисов в клиентском приложении VK Teams

  1. Перейдите в конфигурационный файл /usr/local/nginx-im/html/myteam/myteam-config.json:

    vim /usr/local/nginx-im/html/myteam/myteam-config.json

  2. Добавьте в секцию 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"
},

  3. Добавьте в секцию mini-apps:

    "mini-apps": {
    "calendar-enabled": true
},

  4. Добавьте в секцию 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&params=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"
      },
    }
}

  5. Добавьте в секцию disposition:

    "disposition": {
    "desktop": {
        "leftbar": [
            "tasks",
            "calls",
            "mail",
            "calendar",
            "cloud",
            "orgstructure" // добавьте, если пользуетесь функциональностью структуры организаций
        ]
    },
    "mobile": {
        "services": [
            "discover"
        ],
        "tabs": [
            "calls",
            "tasks",
            "mail",
            "calendar",
            "orgstructure" // добавьте, если пользуетесь функциональностью структуры организаций
        ]
    }
}

Шаг 11. Пересоздайте pod админ-консоли

Выполните команду:

kubectl delete pod -n vkteams myteam-admin-<pod ID>

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

Примечание

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

  1. Получите access_token <webapi-token>:

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

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

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

      Примечание

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

  2. На сервере VK Teams выполните команды:

    1. В файле vim /usr/local/nginx-im/html/myteam/myteam-config.json включите флаг save-to-cloud-enabled:true.

    2. Примените изменения:

      kubectl delete pod myteam-admin-<pod ID> -n vkteams

    3. В файле vim /usr/local/go.files.icq.com/files.icq.com.config.yaml включите флаг show_cloud_file_status: true.

    4. Перезапустите службу: 

      systemctl restart gofiles_httpd

    5. Отредактируйте файл /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

    6. Перезапустите службу:

      systemctl restart skywalker-1.service

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

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

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

Шаг 1. Включите интеграцию с VK Teams

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

  1. Нажмите на кнопку в правом верхнем углу, выберите пункт Продукты.

  2. Включите следующие компоненты:

    • Интеграция с VK Teams.
    • Календарь: бот календаря для VK Teams.
    • Бот новых почтовых сообщений для VK Teams.

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

  4. Перейдите на вкладку AdminPanel.

  5. Сгенерируйте новые контейнеры:

    • Если Почта VK WorkSpace установлена на одной машине, нажмите на кнопку Сгенерировать автоматически.

    • В случае распределенной установки:

      1. Нажмите Добавить → Несколько контейнеров.
      2. Установите фильтр Установлено не более 0.
      3. Распределите недостающие контейнеры по гипервизорам с учетом дублируемости.
      4. Нажмите на кнопку Добавить.

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

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

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

    Название поля Значение
    Адрес 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. Заполните данные ботов в веб-интерфейсе установщика Почты

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

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

    Название поля Значение
    Адрес 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. Завершите настройку

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