Каталог приложений
В каталоге перечислены партнёрские приложения, которые оператор вашего PBX проверил и одобрил. Администратор устанавливает приложение для компании. Установленное приложение входит в ваш PBX через его собственный сервер авторизации OAuth 2.1 с теми правами, которые оно заявило, и не больше. Платежей в каталоге нет.
Установка приложения
Откройте Админ > Подключения > Каталог приложений (/admin/marketplace). Для просмотра нужно integrations:read, для установки и удаления — integrations:write.
- Найдите приложение в разделе Доступные приложения. В записи указаны издатель, версия и права, которые приложение получает.
- Нажмите Установить. В диалоге повторяются права: приложение сможет входить только с ними, и каждый пользователь всё равно подтверждает его на странице согласия.
- Приложение появится в разделе Установленные приложения с Идентификатором клиента 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).
- Зарегистрировать издателя: идентификатор издателя (от 2 до 40 строчных букв, цифр или дефисов, начинается с буквы), название и контакт по безопасности.
- Зарегистрировать ключ подписи: идентификатор ключа (от 3 до 64 строчных букв, цифр, точек, подчёркиваний или дефисов) и открытый ключ Ed25519 из 44 символов base64 (32 байта). Закрытый ключ никогда не покидает издателя.
- Для замены зарегистрируйте новый ключ и отзовите старый кнопкой Отозвать ключ подписи. Отозванный ключ не проверяет новые заявки. Уже проверенные версии остаются как есть.
Что отправляет партнёр
Партнёр подписывает ключом 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/installs | integrations: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.
- Установка остаётся на своей версии. Нет уведомления об обновлении и повторного согласия, когда новая версия запрашивает другие права.