Пользователи, отделы и роли
Всё здесь доступно через API (/users, /departments, /roles, /permissions). Веб-консоль администратора содержит страницы для пользователей, отделов, ролей, внутренних номеров, устройств и истории; полным справочником служит API (/api/docs).
Отделы
Отделы объединяют пользователей, внутренние номера и устройства. Роль может быть выдана на всю компанию или на один отдел. У каждой компании есть отдел по умолчанию: его можно переименовать, но нельзя переместить или удалить. Пользователь, созданный без отдела, попадает туда. Тот, кто не имеет прав на всю компанию, должен явно указать отдел при создании пользователя.
Пользователи
Страница «Пользователи». Консоль также адаптируется к экранам размером с телефон (следующее изображение).
Та же страница на экране шириной 390 пикселей.
- Новому пользователю назначается встроенная роль Пользователь для всей компании (свои вызовы, голосовая почта, справочник). Любая другая роль назначается через
POST /users/{id}/roles. passwordпри создании необязателен, проверяется по политике паролей и никогда не возвращается.- Отключение пользователя сразу завершает все его сеансы и блокирует вход.
- Сброс пароля администратором (
POST /users/{id}/password-reset) задаёт новый пароль, снимает блокировку и завершает сеансы пользователя. Пароль передаётся только в теле запроса; ответ —204без тела. - Сброс двухфакторной аутентификации (
POST /users/{id}/two-factor-reset) удаляет регистрацию TOTP пользователя и завершает его сеансы. - Вы не можете отключить или удалить себя (
MPBX-USER-SELF), а последнего Владельца на уровне компании нельзя ни отключить, ни удалить, ни лишить роли (MPBX-RBAC-LAST-OWNER).
Политика паролей и блокировка
Пароли должны содержать не менее 12 символов (не более 128) и не требуют обязательного набора разных типов символов. Распространённые пароли, ряды клавиатуры, повторяющиеся символы и собственное имя или e-mail пользователя отклоняются. После 5 неудачных входов в течение 15 минут учётная запись блокируется на 15 минут; каждая последующая блокировка подряд удваивает срок, но не более чем до 1 дня. Сброс пароля администратором снимает блокировку.
Импорт и экспорт CSV
GET /users/export выгружает пользователей, которых вы можете читать, в формате CSV. POST /users/import (text/csv, не более 5 МиБ и 2000 строк) читает тот же формат:
email,first_name,last_name,locale,department,status,extension
ana.ruiz@acme.example,Ana,Ruiz,es-MX,Sales,active,1001
email обязателен. Строки сопоставляются с пользователями по e-mail: существующие пользователи обновляются, новые создаются, а пустые ячейки не меняют существующих значений. Пароли не входят в файл. Импорт по умолчанию выполняется как пробный прогон (dry_run=true): отчёт показывает действие и ошибки для каждой строки, но ничего не записывается. При dry_run=false файл применяется, только если все строки корректны; иначе ничего не записывается и вы получаете 422 MPBX-IMPORT-INVALID.
Роли и разрешения
Встроенные роли и число разрешений в каждой из них.
Разрешение — это ключ, например queues:read. Тот же ключ служит областью действия ключей API и каждой операции API. Роль — это именованный набор разрешений. Роль назначается пользователю на всю компанию или на один отдел.
Шесть встроенных ролей есть в каждой компании, и они доступны только для чтения (MPBX-RBAC-BUILTIN-READONLY): Пользователь, Секретарь, Супервайзер, Администратор отдела, Менеджер и Владелец. Для всего остального создайте собственную роль через POST /roles из списка разрешений (GET /permissions).
Как вычисляются разрешения:
- Назначение на всю компанию даёт разрешения роли везде в компании.
- Назначение на отдел даёт разрешения роли, ограниченные отделом, только в этом отделе. Разрешения уровня компании (транки, планы набора, роли) назначением на отдел не выдаются.
- Права суммируются. Разрешения читаются из базы данных при каждом запросе, поэтому изменение роли применяется к следующему запросу.
- Пользователь из отдела «Продажи», имеющий разрешение уровня отдела, видит и редактирует только ресурсы отдела «Продажи». Ресурс другого отдела получает ответ
403(MPBX-RBAC-FORBIDDEN), а ресурс другой компании —404.
GET /me показывает, какими правами обладает вызывающий пользователь и где они действуют.
Запрет эскалации и кто кого может менять
- Никто не может выдать разрешение, которого сам не имеет в этой области (
MPBX-RBAC-ESCALATION). Администратор отдела «Продажи» может выдать роль в «Продажах», но не в другом отделе и не на всю компанию. - Действия над другой учётной записью (сброс пароля или двухфакторной аутентификации, отключение, удаление, смена e-mail или отдела) требуют права
users:writeдля отдела этой учётной записи и каждого разрешения, которое есть у этой учётной записи. Поэтому администратор отдела не может сбросить пароль Владельца, который состоит в его отделе (MPBX-ACCOUNT-OUTRANKS).
Системные роли
Над всеми компаниями стоят две роли уровня установки: System Admin и System Owner. Их порядок: System Owner > System Admin > нет. Субъект может изменять учётную запись с системной ролью, только если его собственный системный ранг строго выше, с одним исключением: System Owner может изменять другого System Owner.
| Действует как | Учётная запись System Owner | Учётная запись System Admin | Учётная запись без системной роли |
|---|---|---|---|
| System Owner | да | да | да |
| System Admin | нет | нет | да |
| Любой другой (каждый субъект компании, включая Владельца компании, и каждый ключ API) | нет | нет | да |
Отказы возвращают 403 MPBX-ACCOUNT-SYSTEM. Учитывается ранг токена, который используется: токен уровня компании или ключ API не имеет системного ранга, даже если его пользователь имеет системную роль. System Admin может выдать роль System Admin, только System Owner выдаёт роль System Owner, и никто не выдаёт системную роль себе или роль выше собственной. Последнего System Owner удалить нельзя.
Ключи API
Ключ API создаёт вошедший пользователь с правом api_keys:write — для себя. Его области действия должны быть разрешениями компании, которыми обладает создатель. Ключ передаётся как Authorization: Bearer mpbx_k1_... и никогда не может сделать больше, чем может его владелец в данный момент. Отозванные, истёкшие и неизвестные ключи отклоняются одним и тем же кодом (MPBX-APIKEY-INVALID).
Оптимистичный контроль конкурентных изменений
PATCH и DELETE требуют заголовок If-Match со значением ETag из последнего GET. Отсутствующий заголовок даёт 428, устаревший — 412. См. Начало работы с API.