Подключения OAuth
Некоторые коннекторы входят в другую систему через OAuth 2.0, а не по вставленному токену. MonoPbx хранит одно подключение OAuth на каждый установленный коннектор, обновляет его до истечения срока и сообщает, когда нужно войти снова.
Подключениями управляют в разделе Админ > Подключения > Интеграции (/admin/integrations). Для просмотра статуса нужно integrations:read. Для кнопок Подключить, Переподключить и Отключить нужно integrations:write.
Подключение
- Установите коннектор в разделе Интеграции и заполните его настройки.
- Нажмите Подключить. Браузер перейдёт в другую систему для входа.
- Разрешите доступ. Браузер вернётся на
/admin/integrations/oauth/callback, статус изменится на Подключено, и будет показано, до какого времени действует токен.
Вход использует поток кода авторизации с PKCE (S256). Ожидающий вход действует десять минут и срабатывает один раз. Вход, срок которого истёк, который уже использован или принадлежит другой компании, отклоняется: нажмите Подключить снова.
Кнопка Подключить показывается только для коннекторов, для которых на вашем PBX есть провайдер OAuth. Оператор регистрирует MonoPbx как приложение в каждой системе и перечисляет его в файле провайдеров, указанном в MPBX_INTEGRATIONS_OAUTH_FILE; адрес перенаправления для регистрации: https://<ваш PBX>/admin/integrations/oauth/callback.
Статус
| Статус | Значение |
|---|---|
| Не подключено | Входа не было. |
| Подключено | Токены работают. |
| Требуется повторный вход | Другая система окончательно отказала в обновлении токенов (например, invalid_grant, invalid_client или ответ 401). Нажмите Переподключить. |
MonoPbx обновляет токен доступа примерно за пять минут до истечения срока (не более чем за половину срока жизни) и сохраняет refresh token, который другая система меняет. При временном сбое старый токен остаётся, а повтор выполняется через 1, 2, 4 минуты и так далее, до часа. Окончательный отказ устанавливает статус Требуется повторный вход и вызывает событие integration.needs_reconnect, которое можно получать по WebSocket событий и в вебхуках.
Отключение и удаление
Отключить просит другую систему отозвать токены, затем удаляет их из MonoPbx. Интеграция не работает, пока вы не подключитесь снова. Если другая система недоступна, токены всё равно удаляются в MonoPbx, а отзыв выполняется по возможности. Удаление интеграции делает то же самое.
Токены зашифрованы ключом вашей компании. Ни один экран и ни один ответ API не возвращает токен, и ни один не попадает в журнал.
API
| Вызов | Право |
|---|---|
GET /api/v1/integrations/installs/{id}/oauth: входит ли коннектор здесь через OAuth, и его подключения | integrations:read |
POST /api/v1/integrations/installs/{id}/oauth/start: адрес для открытия | integrations:write |
POST /api/v1/integrations/oauth/callback: завершить вход, передав state и code | integrations:write |
DELETE /api/v1/integrations/installs/{id}/oauth/{connection_id}: отключить | integrations:write |
Ограничения
- Консоль показывает и запускает подключение компании.
- Адреса входа провайдера заданы для коннектора, поэтому коннектор, адреса которого зависят от аккаунта (Kommo, Bitrix24), работает с одним аккаунтом на PBX. См. Kommo, Bitrix24 и Odoo.
- Jira, синхронизация календарей и шаблоны CRM сохраняют собственный вход.