Перейти к основному содержимому

Каталог приложений

В каталоге перечислены партнёрские приложения, которые оператор вашего PBX проверил и одобрил. Администратор устанавливает приложение для компании. Установленное приложение входит в ваш PBX через его собственный сервер авторизации OAuth 2.1 с теми правами, которые оно заявило, и не больше. Платежей в каталоге нет.

Установка приложения​

Откройте Админ > Подключения > Каталог приложений (/admin/marketplace). Для просмотра нужно integrations:read, для установки и удаления — integrations:write.

  1. Найдите приложение в разделе Доступные приложения. В записи указаны издатель, версия и права, которые приложение получает.
  2. Нажмите Установить. В диалоге повторяются права: приложение сможет входить только с ними, и каждый пользователь всё равно подтверждает его на странице согласия.
  3. Приложение появится в разделе Установленные приложения с Идентификатором клиента OAuth. Передайте этот идентификатор приложению. Затем приложение выполняет вход на вашем PBX.

Чтобы убрать приложение, нажмите Удалить в разделе Установленные приложения. Все токены приложения перестанут работать сразу. Установка и удаление записываются в журнал аудита и вызывают события integration.installed и integration.removed с коннектором marketplace:<app_id>.

Как работает ограничение: установка регистрирует в вашей компании клиент OAuth, потолок прав которого в точности равен манифесту приложения. При входе каждый пользователь может дать приложению только те запрошенные права, которые входят в этот потолок и есть у самого пользователя.

Очередь проверки для оператора​

Системные администраторы открывают Админ > Проверка приложений (/admin/marketplace/review). Для просмотра нужно system.settings:read, для действий — system.settings:write.

Заявка проходит такие состояния:

отправлена -> на проверке -> одобрена -> отозвана
|-----> отклонена

Заявку также можно отозвать из состояний «отправлена» и «на проверке». Устанавливаются и показываются только одобренные версии. «Отклонена» и «отозвана» — конечные состояния: издатель отправляет новую версию. Отозванное приложение нельзя установить снова, но компании, у которых оно есть, сохраняют его до удаления.

Для каждой заявки показаны подписанный манифест и контрольный список по лицензиям и безопасности. Для Одобрить нужно отметить все пункты, для Отклонить — написать заметку для издателя:

  • Все включённые зависимости имеют разрешающую лицензию.
  • Лицензия и уведомления о сторонних компонентах опубликованы.
  • Внутри PBX не работает код с копилефтом или с доступными исходниками (source-available).
  • Каждое запрошенное право нужно для описанной в документации функции.
  • Каждый адрес перенаправления и хост вебхука принадлежит издателю.
  • Каждая конечная точка использует HTTPS с действительным сертификатом.
  • Приложение проверяет подписи вебхуков и окно повторов.
  • Токены хранятся зашифрованными, не попадают в журналы и обновляются.
  • Политика конфиденциальности описывает, какие данные звонков хранятся, где и как долго.
  • Опубликованы контакт по безопасности и процесс раскрытия уязвимостей.
  • Расширения консоли работают в изолированном фрейме.

Издатели и ключи подписи​

На той же странице раздел Издатели и ключи подписи регистрирует партнёра и его ключи (system.settings:write).

  1. Зарегистрировать издателя: идентификатор издателя (от 2 до 40 строчных букв, цифр или дефисов, начинается с буквы), название и контакт по безопасности.
  2. Зарегистрировать ключ подписи: идентификатор ключа (от 3 до 64 строчных букв, цифр, точек, подчёркиваний или дефисов) и открытый ключ Ed25519 из 44 символов base64 (32 байта). Закрытый ключ никогда не покидает издателя.
  3. Для замены зарегистрируйте новый ключ и отзовите старый кнопкой Отозвать ключ подписи. Отозванный ключ не проверяет новые заявки. Уже проверенные версии остаются как есть.

Что отправляет партнёр​

Партнёр подписывает ключом Ed25519 точные байты манифеста (схема 1, JSON до 64 КиБ) и отправляет манифест, идентификатор ключа и подпись через оператора на POST /api/v1/system/marketplace/submissions. Подпись неизвестного, отозванного или чужого ключа, а также подпись, не совпадающая с байтами, отклоняется с MPBX-MKT-SIGNATURE. Манифест, не соответствующий схеме, отклоняется с MPBX-MKT-MANIFEST-INVALID.

В манифесте указаны идентификатор и версия приложения, издатель, от 1 до 32 прав (никогда не system.*), от 1 до 8 адресов перенаправления и, при необходимости, вебхуки, точки расширения консоли и описание коннектора. Неизвестные поля отклоняются, и каждый адрес должен быть https. Каждая версия — отдельная заявка.

API​

ВызовПраво
GET /api/v1/marketplace/apps, GET /api/v1/marketplace/installsintegrations:read
POST /api/v1/marketplace/apps/{app_id}/install, DELETE /api/v1/marketplace/installs/{app_id}integrations:write
Издатели, ключи и очередь проверки в /api/v1/system/marketplace/...system.settings:read и system.settings:write

Что важно знать​

  • Партнёры отправляют приложения через оператора с системными учётными данными.
  • Установка выдаёт приложению его OAuth-клиент. Она не создаёт вебхуки, не добавляет страницы консоли и не запускает коннектор на вашем PBX.
  • Установка остаётся на своей версии. Нет уведомления об обновлении и повторного согласия, когда новая версия запрашивает другие права.