Перейти к содержанию

Аутентификация и роли

Все запросы к API Synth, кроме проверки здоровья (GET /health), требуют аутентификации — без неё сервер отвечает 401. Каждый запрос проверяется на права: роль пользователя определяет, какие разделы и действия ему доступны.

Роли

Synth использует четыре роли. Они приходят из OIDC-токена либо назначаются сервером (API-ключ, локальный режим).

Роль Что доступно
ADMIN Полный доступ: админские разделы интерфейса, управление настройками и политиками, регистрация серверов и инструментов, включение шлюза безопасности
USER Обычная работа: сессии, проекты, инструменты, разрешённые политикой
LEAD Дашборд и управление сессиями и проектами команды в дополнение к возможностям USER
AUDITOR Доступ к аудиту и логам; рабочее изменение данных не предполагается

Поддерживаются также пользовательские роли, но при сопоставлении с Keycloak распознаются только перечисленные выше имена.

Режимы аутентификации

Включается переменной SYNTH_AUTH_DEBUG=true. Предназначен только для локальной разработки: сервер принимает встроенные тестовые ключи с разными ролями, чтобы проверять сценарии доступа.

Только для разработки

Debug-режим нельзя включать в продакшене: он подменяет реальную проверку личности. Тестовые ключи не попадают в репозиторий и не используются на боевых стендах.

Для развёртываний без OIDC. Ключ задаётся переменной SYNTH_API_KEY (или --api-key у synth serve) и предъявляется в заголовке:

Authorization: Bearer <api-key>

Ключ даёт роль ADMIN. Храните его в секретах и не коммитьте.

Продакшен-вариант для корпоративного входа. Backend работает как OIDC-клиент Keycloak, после обмена кода/пароля проверяет токены через JWKS и извлекает роли. Сессия поддерживается cookie user_session. Настройка описана в разделе SSO / Keycloak.

Режим synth serve — локальный инстанс без внешнего провайдера идентичности. Единый локальный API-ключ даёт роль ADMIN; если ключ не задан явно, он создаётся в {dataDir}/secrets/api-key. Сервер по умолчанию слушает только 127.0.0.1.

В гибридном режиме роли приходят с удалённого сервера, а не назначаются локально.

Как выдаются права

  1. Пользователь проходит аутентификацию (ключ, debug, OIDC, локальный ключ).
  2. Сервер определяет роль: из токена OIDC, из настройки API-ключа или из локального режима.
  3. На каждом запросе проверка прав пропускает или отклоняет действие. Для админских эндпоинтов нужен ADMIN, для аудита — AUDITOR или ADMIN.

Роли — это верхний уровень контроля. Что именно разрешено агенту внутри сессии, дополнительно регулируют режим сессии и гранулярные права на инструменты (см. Безопасность).

Наследование

Правила доступа и разрешения наследуются саб-агентами: дочерний агент не может получить больше прав, чем сессия, в которой он запущен.

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

Убедиться, что ключ работает, можно запросом к защищённому эндпоинту:

curl -s -H "Authorization: Bearer <api-key>" \
  http://localhost:5000/api/v2/sessions
  • 200 — ключ принят, права позволяют операцию;
  • 401 — аутентификация не пройдена (нет или протух ключ/токен);
  • 403 — аутентификация пройдена, но прав на действие недостаточно.

Что дальше