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

Настройка интеграции 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 указажите 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,
            "url": "https://di.<vkt-domain>.ru/structure",
            "url-dark": "https://di.<vkt-domain>.ru/structure"
          },
        }
    }
    

  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 .