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

API-ресурсы и скоупы

API-ресурсы представляют защищённые API в вашей системе. Каждый ресурс определяет свой набор скоупов (разрешений), которые можно назначать ролям.

Создание API-ресурса​

  1. Откройте Админ-панель по адресу /admin
  2. Перейдите к нужному realm
  3. Откройте API Resources > Create
  4. Заполните поля:
    • Name -- человекочитаемое название (например "Blog API")
    • Indicator -- URI аудитории (например https://api.example.com). Это значение используется как claim aud в JWT-токенах.
    • Access Token TTL -- время жизни токена в секундах (по умолчанию: 3600)

Добавление скоупов​

После создания ресурса добавьте скоупы для определения разрешений:

  1. Откройте API-ресурс
  2. Перейдите в секцию Scopes
  3. Нажмите Add Scope
  4. Введите name (например read:posts) и description

Соглашение об именовании​

Используйте шаблон action:entity для ясности:

read:posts       -- чтение постов блога
write:posts      -- создание/обновление постов
delete:posts     -- удаление постов
admin:users      -- управление пользователями

Запрос токенов для ресурса​

При запросе токенов укажите параметр resource, чтобы указать, для какого API предназначен токен:

curl -X POST https://your-domain.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

Результирующий JWT будет содержать:

  • aud -- indicator ресурса
  • scope -- только предоставленные скоупы для этого ресурса

Встроенный Management API​

Каждый realm автоматически создаёт ресурс Management API. Его indicator:

https://your-domain.com/api/v1/{realmUUID}

Этот ресурс содержит предопределённые скоупы для управления пользователями, приложениями, ролями, ресурсами, провайдерами и настройками. Полный список скоупов см. в разделе RBAC.

Проверка скоупов в API​

После проверки подписи и срока действия JWT проверьте claim scope:

const scopes = decodedToken.scope.split(' ');
if (!scopes.includes('read:posts')) {
  return res.status(403).json({ error: 'Insufficient scope' });
}

Полные примеры см. в разделе Защита API.