Интеграция IVA One с IVA MCU

Время между серверами IVA MCU, IVA One и IVA ID должно быть синхронизировано с высокой точностью

Установка и предварительная настройка IVA MCU

выполнить установку IVA MCU

Если используется самоподписанный сертификат, то при первичной настройке IVA MCU на шаге Установка SSL-сертификата загружается цепочка, состоящая из сертификата домена и сертификата CA. Подробнее: Требования к сертификатам

После установки сертификата может потребоваться перезапуск модуля Nginx:

Веб-панель администрирования IVA MCU → Перейти в раздел Модули системы → Выбрать сервер → Выбрать модуль nginx → Нажать Рестарт

Если для отправки приглашений на мероприятия будет использоваться IVA Mail, необходимо:

Веб-панель администрирования IVA MCU → Перейти в раздел Системные настройки → Выбрать секцию Экспериментальные настройки → Выключить флаговую кнопку Почтовые уведомления о мероприятиях → Нажать Сохранить

выполнить вход в веб-панель администрирования IVA MCU по DNS-имени домена IVA MCU
убедиться, что в IVA MCU используется установленный TLS-сертификат
отключить Режим SFU в звонках чата: Перейти в раздел Системные настройки → Выбрать секцию Настройки WebRTC → Выключить флаговую кнопку Режим SFU в звонках чата → Нажать кнопку Сохранить
создать несколько учетных записей пользователей IVA MCU для дальнейшей проверки
включить расширенный поиск пользователей на сервере:
Перейти в раздел Системные настройки → Выбрать секцию Системные настройки → Включить флаговую кнопку Поиск среди всех зарегистрированных пользователей
предоставить созданным пользователям доступ к конференциям, вебинарам и звонкам:
Перейти в раздел Пользователи → Выбрать Имя домена → Нажать кнопку Список пользователей → Выбрать / найти пользователя → Нажать кнопку Детально → Перейти во вкладку Подписки → В строке Доступные типы мероприятий включить флаговые кнопки: Конференции, Вебинары и Звонки
проверить, что между пользователями работают чаты и звонки:
Авторизоваться в IVA MCU под учетной записью пользователя → Контакты → Выбрать пользователя → Перейти в персональный чат → Отправить сообщение / совершить звонок
Подробнее: Руководство пользователя IVA Connect Web

Регистрация SSO-сервера IVA ID в IVA MCU

Для настройки интеграции IVA MCU с IVA ID необходимо:

добавить SSO-сервер:
Веб-панель администрирования IVA MCU → Перейти в раздел Внешняя аутентификация → Выбрать домен → Нажать кнопку SSO сервера → Нажать кнопку Добавить SSO сервер

Создание SSO-сервера:

Название: IVA ID
Тип сервера: IVA_ID
URL идентификатора сервера: значение поля issuer из IVA ID
URL аутентификации: значение поля authorization_endpoint из IVA ID

URL получения токена доступа: значение поля token_endpoint из IVA ID

Для определения URL идентификатора сервера, URL аутентификации и URL получения токена необходимо:
Войти в IVA ID → Нажать Manage Realms → Выбрать IVA → Перейти в раздел Realm settings → Перейти на вкладку General → Нажать на ссылку OpenID Endpoint Configuration → Скопировать значения полей

URL идентификатора сервера, URL аутентификации и URL получения токена доступа можно определить, пройдя по ссылке:
https://<IVA_ID_DOMAIN>/realms/IVA/.well-known/openid-configuration

ID клиента: iva-mcu

Закрытый ключ клиента: значение Client Secret из IVA ID

Для определения закрытого ключа клиента необходимо:
Войти в IVA ID → Нажать Manage Realms → Выбрать IVA → Перейти в раздел Clients → Перейти на вкладку Credentials → В строке Client Secret нажать кнопку Regenerate и скопировать значение

URL брокера сообщений: nats://<IP_ADDRESS>:<EXTERNAL_PORT>
где:

<IP_ADDRESS> — внутрисетевой адрес балансировщика IVA One. Рекомендуется указывать IP-адрес для обращения IVA MCU напрямую к компоненту EventBus (шине событий) IVA One

<EXTERNAL_PORT> — порт компонента EventBus IVA One (значение по умолчанию: 32222). Подробнее — Настройка EventBus

Для определения порта необходимо:

на сервере IVA One открыть файл /opt/iva/values.yaml командой
```
sudo nano /opt/iva/values.yaml
```
скопировать содержимое поля externalPort

Keystore брокера сообщений: значение вывода команд на сервере IVA One:

Последовательность указания объектов должна строго соблюдаться:

сертификат CA (ca.crt)
публичный ключ (tls.crt)
приватный ключ (tls.key)

sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.ca\.crt}' | base64 --decode
sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.tls\.crt}' | base64 --decode
sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.tls\.key}' | base64 --decode

Truststore брокера сообщений: значение вывода команды на сервере IVA One:
```
sudo kubectl -n default get secret iva-mcu-eventbus-secret -o jsonpath='{.data.ca\.crt}' | base64 --decode
```

Публичный ключ сервера: публичный сертификат IVA ID

Для определения публичного сертификата IVA ID необходимо:
Войти в IVA ID → Нажать Manage Realms → Выбрать IVA → Перейти в раздел Realm settings → Перейти на вкладку Keys → Выбрать RS256 и нажать кнопку Certificate → Скопировать содержимое

включить флаговую кнопку Возможность создания мероприятий новыми пользователями

нажать кнопку Создать

для созданного SSO-сервера нажать кнопку Синхронизировать

Во время синхронизации выполняется создание и обновление пользователей IVA MCU, созданных в IVA ID.
Блокировка пользователей, созданных ранее при синхронизации с IVA ID, выполняется, если они были удалены в IVA ID

После регистрации SSO-сервера может потребоваться перезапуск службы ivcs-server.service. Для этого необходимо в консоли головного сервера IVA MCU выполнить команду:

sudo systemctl restart ivcs-server.service

Проверка успешной синхронизации

При успешной синхронизации в файле лога ivcs-server.log должна появиться строка, содержащая URL брокера сообщений, вида:

NATS connected. ExternalAuthProviderId:0be2875f-e099-4873-93d2-a186bb4b6457. NATS url:nats://<IP_ADDRESS>:<EXTERNAL_PORT>

Посмотреть содержимое файла ivcs-server.log можно следующими способами:

через консоль управления:
- в консоли головного сервера IVA MCU выполнить команду:
  sudo tail -f -n 1000 /var/log/ivcs-server/ivcs-server.log
через веб-панель администрирования IVA MCU:
- скачать dump-файл: Перейти в раздел Модули системы → Выбрать необходимый сервер → Нажать ссылку Скачать dump файл
- открыть скачанный архив и перейти в папку diagnostic-main-ХХХ\ivcs-server\files\var\log\ivcs-server
- открыть файл ivcs-server.log

Регистрация приложения IVA One в IVA MCU

Для регистрации приложения IVA One в IVA MCU необходимо:

задать значение IVA One URL:
Веб-панель администрирования IVA MCU → Перейти в раздел Домены → Выбрать домен → Нажать кнопку Детально → Выбрать секцию Экспериментальные настройки → Ввести адрес IVA One в поле IVA One URL: https://<IVA_ONE_DOMAIN> (где <IVA_ONE_DOMAIN> — доменное имя IVA One, например one.example.ru) → Нажать кнопку Сохранить

После применения данной настройки IVA MCU будет функционировать в режиме интеграции с IVA One и поддерживать только участие в мероприятиях. Вход в мероприятия будет возможен только через IVA One

указать значение параметра Хост переадресации на мероприятие:
Веб-панель администрирования IVA MCU → Перейти в раздел Домены → Выбрать домен → Нажать кнопку Детально → Выбрать секцию Системные настройки → Хост переадресации на мероприятие: указать <IVA_ONE_DOMAIN> (доменное имя IVA One) → Нажать кнопку Сохранить
указать разрешенные домены CORS:
Веб-панель администрирования IVA MCU → Перейти в раздел Системные настройки → Выбрать секцию Настройки HTTP → Заполнить следующие поля:
- Разрешенные домены CORS для клиентского API: <IVA_ONE_DOMAIN>
- Разрешенные домены CORS для интеграционного API: <IVA_ONE_DOMAIN>
- Разрешенные домены CORS для чат-бот API: <IVA_ONE_DOMAIN>
настроить синхронизацию аватаров пользователей с IVA ID:
Веб-панель администрирования IVA MCU → Перейти в раздел Системные настройки → Выбрать секцию Экспериментальные настройки → Ввести адрес IVA One в поле IVA One аватар URL: https://<IVA_ONE_DOMAIN>/api/v1/uploads/<fileId>/avatar → Нажать кнопку Сохранить
добавить интеграционное приложение IVA One:
Веб-панель администрирования IVA MCU → Перейти в раздел Интеграционные приложения → Добавить приложение

Добавление приложения:
- Название: IVA One
- Привилегии: включить флаговые кнопки:
  - Пользователи — Чтение
  - Пользователи — Запись
  - Мероприятия — Чтение
  - Мероприятия — Запись
  - Чат — Чтение
  - Чат — Запись
  - Файл — Чтение
  - Файл — Запись

скопировать и сохранить пароль приложения:
Нажать кнопку Создать → Интеграционное приложение создано → Нажать кнопку Копировать пароль → Нажать кнопку ОК → Сохранить пароль

После нажатия кнопки ОК пароль для приложения нельзя будет посмотреть.
В случае утери пароля, можно создать новый пароль. Для этого необходимо:
Веб-панель администрирования IVA MCU → Перейти в раздел Интеграционные приложения → Выбрать приложение → Нажать кнопку Пересоздать пароль → Создание нового пароля → Нажать кнопку ОК → Новый пароль → Нажать кнопку Копировать пароль → Нажать кнопку ОК → Сохранить пароль

После создания нового пароля приложения старый пароль будет недействителен

скопировать и сохранить ID приложения:
Веб-панель администрирования IVA MCU → Перейти в раздел Интеграционные приложения → Выбрать созданное приложение → Скопировать и сохранить ID приложения
скопировать и сохранить ID домена IVA MCU:
Веб-панель администрирования IVA MCU → Перейти в раздел Домены → Выбрать домен → Нажать кнопку Детально → Выбрать секцию Общие настройки → Скопировать и сохранить ID

Настройка IVA One для интеграции с IVA MCU

на сервере IVA One открыть файл /opt/iva/values.yaml с помощью команды:
```
sudo nano /opt/iva/values.yaml
```
указать параметры подключения к IVA MCU:
```
mcu:
    url: &iva_mcu_url "https://<IVA_MCU_ADDRESS>"
    appId: &iva_mcu_app_id "APP_ID"
    appSecret: &iva_mcu_app_secret "APP_PASS"
    domainId: &iva_mcu_domain_id "DOMAIN_ID"
```
где:
- <IVA_MCU_ADDRESS> — доменное имя (веб-адрес сервера) IVA MCU
- APP_ID — ID приложения IVA One в IVA MCU
- APP_PASS — пароль приложения IVA One в IVA MCU
- DOMAIN_ID — ID домена IVA MCU
применить обновленную конфигурацию values.yaml, выполнив последовательность команд:
```
cd /opt/iva
sudo helm upgrade iva-one ./iva-one -f values.yaml
```

Проверка интеграции IVA One с IVA MCU

Для проверки интеграции IVA One с IVA MCU необходимо:

войти в IVA One с помощью учетной записи пользователя
проверить:
- наличие и доступность в интерфейсе IVA One разделов История звонков и Комнаты
- доступность в чатах аудио- и выдеовызовов, возможность создания ВКС-встреч
- доступность трансляции аудио- и видеоконтента для участников звонков
- возможность создания комнат

Отладка интеграции IVA One с IVA MCU

Проверки

В этом разделе представлен список проверок, которые позволяют устранить самые распространенные ошибки, возникающие в процессе интеграции IVA One с IVA MCU.

В случае появления ошибок необходимо обратиться к специалистам технической поддержки компании IVA Technologies через сервисный портал

Перед обращением в техническую поддержку необходимо убедиться, что:

установленная версия Платформы IVA MCU не ниже 26.0
время между серверами IVA MCU, IVA One синхронизировано с высокой точностью
последовательность указания сертификатов и ключа в Keystore брокера сообщений соблюдена

поддержка интеграции с IVA MCU анонсирована в ответе на запрос из браузера или curl:

https://<IVA_ONE_DOMAIN>/api/v1/system

Пример вывода:

{
  "apiVersion": "1.0.0",
  "auth": {
    "authorizationEndpoint": "https://id.company.ru/realms/IVA/protocol/openid-connect/auth",
    "logoutEndpoint": "https://id.company.ru/realms/IVA/protocol/openid-connect/logout",
    "tokenEndpoint": "https://id.company.ru/realms/IVA/protocol/openid-connect/token"
  },
  "features": {
    "mail": true,
    "mailEvents": true,
    "speechToText": false
  },
  "mcu": {
    "apiBaseUrl": "https://mcu.company.ru/api/rest",
    "server": "https://mcu.company.ru"
  }
....

В случае, если поддержка интеграции не анонсирована, то необходимо перезапустить под calls, выполнив последовательность действий на сервере IVA One:

определить ID пода, выполнив команду:

sudo kubectl get pods | grep calls

Пример вывода:

iva-one-calls-75f677fbbf-8tpgt                1/1     Running   3 (5d13h ago)   5d13h

перезапустить под, выполнив команду:
```
sudo kubectl delete pod <pod_id>
```
где <pod_id> — идентификатор пода calls, полученный в выводе предыдущей команды

Пример команды:
```
sudo kubectl delete pod iva-one-calls-75f677fbbf-8tpgt
```

ошибки в файлах логирования отсутствуют, в особенности для:
- лога пода calls (на сервере IVA One)
- лога /var/log/ivcs-server/ivcs-server.log (на сервере IVA MCU) при обращении к брокеру сообщений NATS

Обновление IVA MCU

Если версия Платформы IVA MCU ниже 26.0, необходимо выполнить обновление Платформы. Для обновления IVA MCU необходимо выполнить действия в соответствии с руководством администратора IVA MCU.