Ролевая модель

Назначение документа#

Документ описывает ролевую модель SmartCPD 6, уровни привилегий, tenant scope и правила проверки доступа в пользовательском интерфейсе и API.

Документ предназначен для администраторов SmartCPD, инженеров внедрения, интеграторов, QA и разработчиков внешних систем.

Основные понятия#

Понятие	Описание
Субъект	Пользователь, API-ключ или внутренний сервис, от имени которого выполняется запрос.
Роль	Набор привилегий, назначаемый пользователю или API-ключу.
Привилегия	Минимальная единица доступа к разделу, действию или API-методу.
Административная роль	Роль с признаком `is_admin_role`. Признак ограничивает возможность назначения роли, но сам по себе не предоставляет привилегий.
Tenant	Клиентский контур данных. В SmartCPD идентификатором tenant является ИНН.
Tenant scope	Набор tenant, в которых субъект может выполнять разрешённые его ролями действия.

Привилегии назначаются субъекту только через роли. Если субъекту назначено несколько ролей, их привилегии объединяются.

Роли являются общими для установки SmartCPD: одна роль может быть назначена субъектам разных tenant. Набор привилегий субъекта одинаков во всех tenant, входящих в его tenant scope.

Статусы сущностей#

В рамках ролевой модели фиксируются статусы следующих сущностей:

Субъект	Возможные статусы	Как интерпретируется
tenant (юридическое лицо)	`active`, `not_active`	Статус для управления доступностью cloud-функциональности комплекса на tenant
user (сотрудник)	`active`, `not_active`, `banned`, `temporary_banned`	`active/not_active` — административные статусы, `banned/temporary_banned` — security-статусы
api_key	`active`, `expired`, `revoked`	`active` — действующий, `expired` — прошёл срок `expires_at`, `revoked` — отозван вручную (`revoked_at`). Статус вычисляется из `revoked_at` и `expires_at`.

Статус tenant не включает и не выключает сам tenant. Он включает и выключает доступную облачную функциональность комплекса для данного tenant. Применимо только для облачных инсталляций. Статус tenant не является флагом наличия лицензии.
temporary_banned назначается системой безопасности при неправильных попытках логина и снимается при успешном входе после тайм-аута, через IDM API unblock или через UI пользователем с привилегией employee.canEdit в пределах доступного tenant. Действие «Снять временную блокировку» восстанавливает прежний административный статус и сбрасывает счётчик неуспешных попыток входа. banned выставляется только через IDM API и снимается только через IDM API. banned не меняется через UI.

Имена привилегий#

Имя привилегии обычно состоит из имени сущности и действия:

*.canSee — просмотр сущности;
*.canEdit — создание и изменение сущности, а для некоторых разделов также удаление и управление статусом;
*.canOrder — запрос операции;
*.canPlay — воспроизведение или получение записи.

Точное назначение каждой привилегии приведено в матрице привилегий.

Различие проверок в UI и API#

Для UI привилегия *.canSee определяет в том числе область видимости и доступность действий над сущностью. Например, *.canEdit не позволяет редактировать сущность, если у пользователя нет доступа к её просмотру через соответствующую *.canSee.

Привилегия отдельного действия сама по себе не создаёт доступный раздел навигации. Для выполнения действия через UI субъекту также нужна основная привилегия просмотра раздела. В частности:

создание, изменение, удаление и управление статусом tenant требуют tenant.canSee вместе с tenant.canEdit;
воспроизведение записей требует cdr.canSee вместе с cdr.canPlay;
открытие карточки текущего tenant требует именно tenant.info.canSee; привилегии работы с лицензией, cloud policy или CDR не предоставляют доступ к этой карточке.

Если после авторизации у пользователя нет ни одного доступного раздела, портал показывает информационную страницу и предлагает обратиться к администратору. Это не означает ошибку аутентификации: назначенные роли не содержат достаточной комбинации привилегий для работы через UI.

Это правило не относится к API. Доступность каждого API-метода определяется только одной требуемой для него привилегией, указанной в контракте этого метода. Клиент API не должен предполагать неявную зависимость *.canEdit от *.canSee.

Разделы UI, использующие несколько API#

В отдельных разделах интерфейс обращается к нескольким API. Основная привилегия предоставляет доступ к разделу, но для отображения его отдельных элементов и выполнения некоторых действий могут дополнительно потребоваться привилегии из других групп.

Раздел или действие	Основные привилегии	Дополнительные привилегии
Создание, редактирование и управление tenant	`tenant.canSee`, `tenant.canEdit`	`license.cloud.canSee` — просмотр лимитов и функций; `license.cloud.canEdit` — их изменение
Информация о tenant	`tenant.info.canSee`; `tenant.info.canEdit` — изменение данных	`license.cloud.canSee` — просмотр эффективных лимитов и функций
Аудит платформы	`audit.canSee`	`setting.canSee` — просмотр настройки аудита; `setting.canEdit` — её изменение
Редактирование пользователя	`employee.canSee`, `employee.canEdit`	`tenant.canSee` — выбор доступного пользователю tenant
Снятие временной блокировки пользователя через UI (`POST /api/v2/tenant/<tenant_inn>/employees/<employee_id>/unlock`)	`employee.canSee` — список сотрудников; `employee.canEdit` — выполнение метода. По умолчанию: `superadmin`, `tenant_admin`; также любая настроенная роль с этими привилегиями	`tenant.canSee` — выбор доступного пользователю tenant; действие выполняется только в пределах доступного tenant
Управление API-ключами	`apiKey.canSee`, `apiKey.canEdit`	`employee.role.canEdit` или `employee.role.admin.canEdit` — назначение соответствующих ролей API-ключу
Создание и редактирование профиля детекции	`detectionSetting.canSee`, `detectionSetting.canEdit`	`license.canSee` — получение доступности SmartContact
Создание и редактирование SIP-маршрута	`sip.canSee`, `sip.canEdit`	`billing.labels.canList` — получение списка тарифных лейблов и назначение лейбла сегменту маршрута
Статистика	`cdr.canSee`; `cdr.canEdit` — загрузка разметки	`cdr.canPlay` — воспроизведение и скачивание записей

Уровни доступа#

Платформа#

Привилегии уровня платформы управляют общими объектами установки: ролями, tenant, глобальными настройками, настройками информационной безопасности, аудитом, ML-моделями и метриками.

Административная роль может содержать как platform-, так и tenant-привилегии. Назначение административных ролей требует отдельной привилегии employee.role.admin.canEdit.

Tenant#

Привилегии уровня tenant управляют объектами выбранного клиента: пользователями, API-ключами, SIP-настройками, профилями детекции, лицензией, биллингом, статистикой и разметкой.

Tenant-привилегия разрешает действие только внутри tenant scope субъекта. Наличие привилегии не расширяет tenant scope.

Tenant scope#

Для пользователя поддерживаются следующие варианты области доступа:

none — только основной tenant пользователя;
list — основной tenant и явно заданный список доступных tenant;
all — все существующие и создаваемые в будущем tenant.

Пользователь не может предоставить другому пользователю доступ к tenant, которого нет в его собственной области доступа.

API-ключ получает роли и tenant-контекст при создании. Для каждого запроса одновременно проверяются требуемая методом привилегия и допустимость целевого tenant.

Роли по-умолчанию#

superadmin#

superadmin — системная административная роль с полным набором поддерживаемых привилегий.

При первичной установке или восстановлении создаётся роль с id=0, именем из SUPERADMIN_ROLE_NAME, признаком административной роли и всеми текущими привилегиями. Роль назначается системному пользователю superadmin с id=0.

Для cloud-установки пользователь superadmin имеет tenant scope all.

Удалить назначенную пользователю роль через UI или API нельзя. Параметры восстановления системной роли и пользователя описаны в документе Установка.

tenant_admin#

tenant_admin — стартовая роль с полным доступом к просмотру и управлению объектами tenant. Она содержит доступные при первичной установке привилегии уровня tenant.

tenant_user#

tenant_user — стартовая роль с полным доступом на просмотр объектов tenant, включая прослушивание доступных записей. Она содержит доступные при первичной установке tenant-привилегии *.canSee и *.canPlay.

Роли tenant_admin и tenant_user автоматически создаются только при первичной установке SmartCPD на пустой БД. При обновлении существующей установки они не создаются и состав их привилегий автоматически не изменяется. Если новая версия добавляет tenant-привилегии, администратору следует при необходимости добавить их в существующие роли самостоятельно.

Эти роли задают начальную модель доступа и могут быть изменены с учётом требований конкретной установки. Как правило, перед назначением пользователям рекомендуется проверить их состав и адаптировать его к принятой в организации модели доступа.

Матрица привилегий#

Привилегии уровня платформы#

Группа в UI	Привилегия	Название в UI	Назначение	Компонент
Пользователи и роли	`role.canSee`	Роли: просмотр	Просмотр ролей и списка доступных привилегий.	`portal-api`
Пользователи и роли	`role.canEdit`	Роли: изменение	Создание, изменение и удаление ролей. Нельзя удалить последнюю назначенную роль, обеспечивающую управление ролями.	`portal-api`
Пользователи и роли	`employee.role.admin.canEdit`	Административные роли пользователя: изменение	Назначение пользователям ролей с `is_admin_role=true`; используется вместе с управлением ролями пользователя.	`portal-api`
Настройки ИБ и Аудит	`audit.canSee`	Аудит: просмотр	Просмотр журнала аудита.	`portal-api`
Настройки ИБ и Аудит	`security.canSee`	Настройки ИБ: просмотр	Отображение настроек информационной безопасности.	`portal-api`
Настройки ИБ и Аудит	`security.canEdit`	Настройки ИБ: изменение	Изменение настроек информационной безопасности. Для общих настроек backend также может требовать `setting.canEdit`.	`portal-api`
Глобальные настройки платформы	`mlModel.canSee`	ML-модели: просмотр	Просмотр доступных ML-моделей.	`config-server`
Глобальные настройки платформы	`mlModel.canEdit`	ML-модели: изменение	Загрузка и обновление ML-моделей.	`config-server`
Глобальные настройки платформы	`setting.canSee`	Глобальные настройки: просмотр	Чтение общих настроек платформы.	`portal-api`
Глобальные настройки платформы	`setting.canEdit`	Глобальные настройки: изменение	Изменение общих настроек платформы.	`portal-api`
Метрики	`metrics.canSee`	Метрики: просмотр	Просмотр Grafana с ролью Viewer и доступ к Prometheus API.	`grafana`, `metrics`
Метрики	`metrics.canEdit`	Метрики: изменение	Административный доступ в Grafana.	`grafana`
Тенанты и лицензии	`tenant.canSee`	Тенанты: просмотр	Просмотр списка tenant и карточки tenant в platform-разделе.	`portal-api`
Тенанты и лицензии	`tenant.canEdit`	Тенанты: изменение	Создание tenant, изменение его карточки и статуса, удаление tenant.	`portal-api`
Тенанты и лицензии	`license.cloud.canSee`	Лимиты и фичи тенанта: просмотр	Просмотр cloud policy, лимитов и доступных функций tenant.	`license-server`
Тенанты и лицензии	`license.cloud.canEdit`	Лимиты и фичи тенанта: изменение	Изменение cloud policy, лимитов и доступных функций tenant.	`license-server`
Биллинг и лицензии	`billing.cloud.canSee`	Облачные тарифы: просмотр	Просмотр глобальных облачных тарифов платформы.	`billing-server`
Биллинг и лицензии	`billing.cloud.canEdit`	Облачные тарифы: изменение	Создание и изменение глобальных облачных тарифов платформы.	`billing-server`

Привилегии уровня tenant#

Группа в UI	Привилегия	Название в UI	Назначение	Компонент
Статистика	`cdr.canSee`	Статистика: просмотр	Просмотр CDR, разметки и истории детекций.	`cdr-collector`
Статистика	`cdr.canEdit`	Статистика: изменение	Загрузка разметки через UI, JSON API или CSV API.	`cdr-collector`
Статистика	`cdr.canPlay`	Статистика: прослушивание	Проверка наличия, воспроизведение и скачивание записей детекций.	`cdr-collector`
Биллинг и лицензии	`billing.canSee`	Биллинг: просмотр	Просмотр текущих данных биллинга и архивной статистики старого биллинга за периоды до миграции.	`billing-server`, `billing-server-legacy`
Биллинг и лицензии	`billing.canEdit`	Биллинг: изменение	Управление тарифами и тарифными лейблами текущего tenant.	`billing-server`
Биллинг и лицензии	`billing.labels.canList`	Биллинг: просмотр тарифных лейблов	Получение списка тарифных лейблов tenant, в том числе для назначения лейбла сегменту SIP-маршрута. Без этой привилегии поле назначения тарифа в настройках сегмента недоступно.	`billing-server`
API и Интеграция	`apiKey.canSee`	API ключи: просмотр	Просмотр API-ключей tenant.	`portal-api`
API и Интеграция	`apiKey.canEdit`	API ключи: изменение	Создание, отзыв, ротация и изменение ролей API-ключа. Назначение ролей дополнительно ограничивается привилегиями управления ролями пользователя.	`portal-api`
Пользователи и роли	`employee.canSee`	Пользователи: просмотр	Просмотр пользователей tenant.	`portal-api`
Пользователи и роли	`employee.canEdit`	Пользователи: изменение	Создание, изменение и удаление пользователей tenant, снятие временной блокировки через UI.	`portal-api`
Пользователи и роли	`employee.password.canEdit`	Пароль пользователя: изменение	Сброс пароля другого пользователя. Не используется для изменения собственного пароля.	`portal-api`
Пользователи и роли	`employee.role.canEdit`	Роли пользователя: изменение	Назначение пользователю неадминистративных ролей.	`portal-api`
SIP и Детекция	`sip.canSee`	Настройки SIP: просмотр	Просмотр маршрутов, входящих и исходящих транков.	`config-server`
SIP и Детекция	`sip.canEdit`	Настройки SIP: изменение	Создание, изменение и удаление SIP-маршрутов и транков.	`config-server`
SIP и Детекция	`detectionSetting.canSee`	Настройки детекции: просмотр	Просмотр профилей детекции, prompts и связанных настроек.	`config-server`
SIP и Детекция	`detectionSetting.canEdit`	Настройки детекции: изменение	Создание, изменение и удаление профилей детекции, prompts и связанных файлов и настроек.	`config-server`
Тенанты и лицензии	`tenant.info.canSee`	Информация о тенанте: просмотр	Просмотр карточки текущего tenant.	`portal-api`
Тенанты и лицензии	`tenant.info.canEdit`	Информация о тенанте: изменение	Изменение реквизитов текущего tenant без platform-level управления tenant.	`portal-api`
Тенанты и лицензии	`license.canSee`	Лицензия: просмотр	Просмотр лицензии tenant и получение fingerprint.	`license-server`
Тенанты и лицензии	`license.canEdit`	Лицензия: изменение	Загрузка лицензии текущего tenant.	`license-server`

Привилегии statistic.canSee и statistic.canEdit сохранены в backend только для совместимости со старым разделом статистики. Они не отображаются в редакторе ролей и не должны назначаться новым ролям. Для актуального раздела «Статистика» используются только cdr.canSee, cdr.canEdit и cdr.canPlay.

Отдельные права запроса счета и просмотра документов старой модели биллинга в SmartCPD 6.0 не используются. Для просмотра как текущего биллинга, так и архивной статистики за периоды до миграции используется billing.canSee. Архивный раздел доступен только если при обновлении установлен billing-server-legacy.

Контекст авторизации#

После проверки пользователя или API-ключа доверенная граница SmartCPD формирует внутренний контекст авторизации. Внутренние сервисы используют готовый контекст и не вычисляют роли заново.

Контекст содержит:

идентификатор субъекта;
основной tenant субъекта;
список эффективных привилегий;
tenant scope;
идентификатор запроса для трассировки, если он передан или сформирован gateway.

Внешний клиент не должен передавать внутренние auth-заголовки. На публичной границе такие заголовки удаляются и заменяются контекстом, сформированным после проверки Bearer API-ключа или пользовательской сессии.

Проверка доступа к API#

Для внешних API используется Bearer API-ключ. Порядок работы и контракты методов приведены в документе External API.

При обработке запроса проверяются:

подлинность субъекта;
наличие одной привилегии, требуемой методом;
наличие целевого tenant в tenant scope субъекта;
корректность параметров запроса.

Отсутствие требуемой привилегии или доступа к tenant приводит к ответу 403 Forbidden. Отсутствие доступной субъекту сущности может приводить к 404 Not Found согласно контракту конкретного метода.

Практические рекомендации#

Для пользовательской роли выдавайте пары *.canSee и *.canEdit, если пользователь должен изменять сущность через UI.
Для API-ключа выдавайте минимальную привилегию, указанную в контракте вызываемого метода.
Не используйте legacy-привилегии statistic.* для новых ролей.
Назначайте административные роли только доверенным администраторам платформы.
Ограничивайте tenant scope минимальным набором tenant, необходимым субъекту.