Управление доступом (RBAC)

VoxKey реализует RBAC через API-ресурсы, скоупы и роли. Это позволяет контролировать, к чему имеют доступ пользователи и приложения в ваших API.

Модель данных

API-ресурсы

API Resource представляет защищенный API в вашей системе. Каждый ресурс содержит:

Name -- человекочитаемое название (например "Blog API")
Indicator -- URI аудитории для запросов токенов (например https://api.example.com)
Access Token TTL -- время жизни токена в секундах для этого ресурса
Scopes -- разрешения, принадлежащие этому ресурсу

Запрос токенов для конкретного ресурса через параметр resource:

curl -X POST https://auth.example.com/oauth2/{realmUUID}/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET \
  -d scope="read:posts write:posts" \
  -d resource=https://api.example.com

Скоупы

Скоупы -- это разрешения, привязанные к API Resource. Они попадают в JWT access-токены как claim scope.

Встроенные OIDC-скоупы (всегда доступны):

openid -- обязателен для OIDC-потоков
profile -- имя пользователя и метаданные
email -- email пользователя
phone -- телефон пользователя
offline_access -- выдача refresh-токенов

Пользовательские скоупы определяются для каждого API Resource (например read:posts, admin:users).

Роли

Роли группируют скоупы и назначаются пользователям или приложениям.

Два типа ролей:

Тип	Назначается	Сценарий
`user`	Пользователям realm	Разрешения конечных пользователей (viewer, editor, admin)
`m2m`	Приложениям	Разрешения для межсервисного взаимодействия

Роль может включать скоупы из нескольких API-ресурсов.

Management API

Каждый realm получает встроенный ресурс Management API со следующими скоупами:

Скоуп	Описание
`all`	Полный доступ ко всем эндпоинтам
`users:read`	Просмотр пользователей
`users:write`	Создание, обновление, удаление пользователей
`users:roles`	Управление назначением ролей
`applications:read`	Просмотр приложений
`applications:write`	Создание, обновление, удаление приложений
`roles:read`	Просмотр ролей
`roles:write`	Создание, обновление, удаление ролей
`resources:read`	Просмотр API-ресурсов
`resources:write`	Создание, обновление, удаление API-ресурсов
`providers:read`	Просмотр провайдеров аутентификации
`providers:write`	Управление провайдерами
`settings:read`	Просмотр настроек realm
`settings:write`	Обновление настроек realm
`logs:read`	Просмотр журналов аудита

Как токены содержат разрешения

При запросе токена VoxKey определяет роли пользователя или M2M-приложения, собирает все предоставленные скоупы, пересекает их с запрошенными и встраивает в JWT:

{
  "sub": "user_abc123",
  "aud": "https://api.example.com",
  "scope": "read:posts write:posts",
  "iss": "https://auth.example.com/oauth2/{realmUUID}",
  "exp": 1711612800
}

Настройка RBAC

Создайте API Resource -- определите URI аудитории и скоупы
Создайте роли -- сгруппируйте скоупы в логические роли
Назначьте роли -- привяжите роли к пользователям или M2M-приложениям
Проверяйте в API -- валидируйте claim scope во входящих JWT

Модель данных​

API-ресурсы​

Скоупы​

Роли​

Management API​

Как токены содержат разрешения​

Настройка RBAC​