RBAC и авторизация

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

Как проверить доступ

Для пользователя выберите системную роль по таблице разрешений ниже, затем назначьте группу и доступные проекты. Для автоматизации создайте сервисную учётную запись и задайте разрешения scope, интерфейсы и проект. Scope — строка разрешения, например query:execute; её значение в настройках и запросах сохраняется без перевода.

Проверьте два запроса: разрешённую операцию и операцию вне назначенных прав. Сопоставьте пользователя или сервисную учётную запись, проект, нужное разрешение и результат в журнале аудита. Так можно определить, какой уровень доступа нужно изменить: роль, назначение проекта или разрешения машинной учётной записи.

Для настройки корпоративного входа используйте руководство OAuth/OIDC и LDAP, а для URL и форматов запросов — справочник REST API.

Модель авторизации

CodeGraph использует три связанных слоя авторизации:

Аутентификация определяет пользователя или машинного субъекта доступа. Авторизация проверяет разрешения роли, строки scope, разрешённые интерфейсы, ограничения группы и проекта. Middleware выполняет дополнительные проверки безопасности.

Пользовательские роли и разрешения

Роли

Системная роль задаёт базовый набор действий пользователя:

Проверка минимальной роли использует иерархию: viewer < analyst < reviewer < admin.

Проверка разрешений

Permission сейчас содержит 31 значение, включая admin:all.

Правила предоставления разрешений:

• Роль admin разрешает любые операции из каталога.
• Явный scope предоставляет разрешение, если его строка совпадает со значением в каталоге.
• Scope admin:all разрешает все операции при проверке ролевых и машинных разрешений.

Проверка ролевого разрешения

Из корня исходного репозитория CodeGraph с установленными Python-зависимостями сохраните пример в check_rbac.py и выполните python check_rbac.py:

from src.api.auth.permissions import Permission, Role, has_permission

assert has_permission(Role.VIEWER, Permission.SCENARIOS_READ)
assert not has_permission(Role.VIEWER, Permission.SCENARIOS_EXECUTE)
assert has_permission(Role.ANALYST, Permission.SCENARIOS_EXECUTE)
assert not has_permission(Role.ANALYST, Permission.REVIEW_EXECUTE)
assert has_permission(Role.REVIEWER, Permission.REVIEW_EXECUTE)
print("Role permission checks passed")

Ожидаемый результат — Role permission checks passed и код завершения 0. Ошибка AssertionError означает расхождение ожидаемого разрешения с реализацией. Пример проверяет только ролевую функцию, без токенов, HTTP и ограничений проекта.

Каталог разрешений

ROLE_PERMISSIONS сейчас не включает USERS_*, API_KEYS_DELETE, METRICS_READ, разрешения цифровых сотрудников только для администратора и ADMIN_ALL для ролей без прав администратора. На практике они доступны через Role.ADMIN или явное разрешение scope admin:all.

Вспомогательные функции разрешений

Для проверки роли и scope используйте src.api.auth.permissions:

from src.api.auth.permissions import (
    Permission,
    Role,
    get_default_scopes_for_api_key,
    get_role_permissions,
    has_all_permissions,
    has_any_permission,
    has_permission,
    validate_scopes,
)

Ключевое поведение:

• get_default_scopes_for_api_key() возвращает scenarios:read, scenarios:execute, query:execute, sessions:read, sessions:write, history:read.
• validate_scopes() фильтрует неизвестные строки по перечислению Permission.
• has_permission() сначала учитывает разрешения роли, затем явные строки scope.

Контекст аутентификации FastAPI

AuthContext определён в src/contracts/auth_context.py и доступен через src.api.auth.middleware. Контекст объединяет субъекта доступа (AuthSubject) и его область разрешений (AuthScope).

Поля:

Последовательность получения контекста:

1. Повторно использовать request.state.machine_principal, если ScopeEnforcementMiddleware уже проверил API-ключ.
2. Проверить X-YC-IAM-Token, если IAM включен.
3. Проверить JWT Bearer-токен и отклонить отозванные идентификаторы JWT.
4. Проверить X-API-Key как машинные учётные данные.
5. Вернуть контекст без аутентификации, если действительных учётных данных нет.

В обработчиках маршрутов используйте эти зависимости:

from src.api.auth.middleware import (
    get_auth_context,
    get_current_user,
    get_optional_user,
    require_admin,
    require_analyst,
    require_any_permission,
    require_auth,
    require_auth_or_localhost,
    require_permission,
    require_reviewer,
    require_role,
)

require_auth_or_localhost() разрешает запросы локального плагина только при security.local_dev_unauthenticated_surfaces_enabled=true и обращении через loopback. Запросы, изменяющие состояние, должны содержать X-Actor-Agent-Id и X-Task-Id; общие идентификаторы агентов, например codex или codex-headless, отклоняются.

src/api/dependencies.py также содержит зависимости, которые читают базу данных и возвращают ORM-объекты User. Маршруты аутентификации используют их для управления учётными записями и API-ключами.

Методы аутентификации

Вход по имени пользователя и паролю

Маршруты доступны под /api/v1/auth:

Администратор создаёт локальную учётную запись через POST /api/v1/admin/identity/users и задаёт её роль; значение по умолчанию — analyst. Ответ содержит одноразово раскрываемый пароль. Локальные пароли хешируются через bcrypt. Для выхода вызовите DELETE /api/v1/me/logout с текущим Bearer-токеном: маршрут добавит токен в список отозванных.

JWT Bearer-токены

Поля TokenPayload:

Значения по умолчанию:

• Срок действия access-токена: настройка access_token_expire_minutes в JWT-конфигурации, если expires_delta не передан. Резервное значение — 30 минут.
• Срок действия refresh-токена: 7 дней.
• Настройки подписи берутся из src/api/config.py (API_JWT_ALGORITHM, определение секрета JWT).

Отзыв:

• blacklist_token() сохраняет отпечаток SHA-256 от JTI в памяти и в таблице token_blacklist.
• is_token_blacklisted() сначала проверяет память, затем базу данных.
• load_blacklist_cache() загружает неистёкшие записи об отзыве при запуске.
• _blacklist_sync_task() периодически обновляет кеш в памяти.

API-ключи пользователей

API-ключи пользователей создаются через /api/v1/me/api-keys и передаются как X-API-Key.

Формат:

rag_<8 hex chars>_<48 hex chars>

Детали реализации:

• generate_api_key() возвращает (full_key, prefix, key_hash).
• Префикс начинается с rag_.
• Секрет генерируется через secrets.token_hex(24).
• Сохранённый хеш: SHA-256.
• verify_api_key() использует secrets.compare_digest().
• ApiKey.group_id может ограничить ключ одной группой.
• API-ключи пользователей аутентифицируются как MachinePrincipal(subject_type="user", auth_method="api_key").
• API-ключи пользователей по умолчанию разрешают интерфейсы api и mcp.
• ApiKeyInfo — модель ответа без секрета.
• ApiKeyWithSecret расширяет ApiKeyInfo и возвращается только при создании ключа.

Создание, чтение и отзыв API-ключей:

Запрос создания по умолчанию использует ["scenarios:read", "query:execute"]; вспомогательная функция нижнего уровня get_default_scopes_for_api_key() возвращает более широкий исторический набор. Для запроса к API используйте значения по умолчанию обработчика маршрута.

Сервисные учётные записи

Сервисные учётные записи используют тот же заголовок X-API-Key, но другой префикс ключа:

svc_<8 hex chars>_<48 hex chars>

Сервисные учётные записи хранятся в service_accounts, их учётные данные — в service_account_credentials.

Средства контроля:

• Управление сервисными учётными записями только для администратора.
• Шаблоны политики: ci, portal, bot, agent.
• Явные scopes и allowed_interfaces.
• Необязательные ограничения group_id или project_id.
• Сроки действия учётной записи и учётных данных.
• Выпуск новых учётных данных без немедленного отзыва старых.
• Ограничение количества активных ключей через security.service_account_max_active_credentials.
• Отзыв ключей и отключение учётной записи.
• Заголовок контракта машинного доступа: X-CodeGraph-Machine-Contract, сейчас 2026-03-v1.
• Необязательная привязка mTLS с завершением TLS на прокси для настроенных интерфейсов.
• Единые события аудита машинного доступа через AuditAction.MACHINE_ACCESS.

Маршруты администратора:

Шаблоны политики:

OAuth2/OIDC

Поддерживаемые провайдеры:

Маршруты:

Пользователи OAuth получают JWT с ролью, сохранённой в базе данных.

LDAP/Active Directory

Маршруты:

LDAPAuthenticator.map_groups_to_role() читает LDAPConfig.role_mapping и нормализует DN/CN-алиасы групп. При нескольких совпадениях выбирается первая роль в порядке admin, reviewer, analyst, viewer. Если совпадений нет, возвращается analyst. Это значение по умолчанию имеет больше разрешений, чем viewer; проверьте сопоставление групп до подключения LDAP.

Yandex Cloud IAM

Проверка IAM находится в src/api/auth/providers/iam.py и инициализируется из настроек API, когда IAM включен.

Заголовок запроса:

X-YC-IAM-Token: <token>

Когда токен действителен, get_auth_context() возвращает:

• role=Role.ANALYST
• scopes=["scenarios:read", "query:execute", "review:execute"]
• auth_method="iam"

Результаты проверки кешируются на настроенный срок действия кеша IAM-токенов.

Проверка разрешений машинных учётных записей

ScopeEnforcementMiddleware добавляется в src/api/main.py, когда security.api_key_scope_enforcement=true. Он проверяет запросы с X-API-Key до вызова обработчика маршрута.

Процесс:

1. Проверить ключ пользователя или сервисной учётной записи.
2. Сохранить MachinePrincipal в request.state.machine_principal.
3. Определить запрошенную область проекта из X-Project-Id.
4. Проверить необязательный заголовок контракта машинного доступа.
5. Проверить необязательную привязку mTLS для сервисной учётной записи.
6. Выполнить authorize_machine_request().
7. Записать событие аудита машинного доступа.
8. Вернуть 403 insufficient_scope при отказе в доступе.

Выдержка из карты разрешений маршрутов API:

Каждый маршрут выполняет свои проверки аутентификации, подписи webhook и зависимостей обработчика. authorize_machine_request() проверяет разрешённый интерфейс и ограничения проекта или группы сервисной учётной записи для любого пути. Карта scope добавляет требуемое разрешение для перечисленных выше префиксов.

Карта разрешений маршрутов MCP:

Только для MCP разрешение mcp:access может подтверждаться альтернативными scope: query:execute, scenarios:read, scenarios:execute, review:execute, stats:read, history:read и admin:all.

Явная проверка scope в обработчике:

В приложении FastAPI импортируйте Depends из fastapi и создайте объект router типа APIRouter. Добавьте обработчик из примера и подключите маршрутизатор к приложению. После настройки аутентификации отправьте запросы от учётных записей с требуемым scope и без него, чтобы проверить оба результата доступа.

from src.api.auth.tokens.scope_enforcement import require_scope

@router.get("/example")
async def example(auth=Depends(require_scope("query:execute"))):
    ...

require_scope() проверяет строки AuthContext.scopes; admin:all обходит эту проверку.

Доступ к группам и проектам

Авторизация доступа к группе и проекту отделена от глобальных ролей пользователей.

Перечисления и таблицы:

Маршруты администратора для управления доступом:

Назначьте роль и проекты через интерфейс

Для этого нужны права администратора, созданный пользователь и группа с проектами. В интерфейсе группа называется «Тенант».

1. Откройте раздел «Пользователи» и выберите карточку пользователя.
2. Заполните «Тенант аудита» и «Причина изменения»: они сохраняют контекст административной операции.
3. В разделе «Системная роль» выберите роль по таблице разрешений выше, сохраните её и подтвердите изменение.
4. На вкладке «Доступ» добавьте тенант и выберите роль в нём: «Наблюдатель», «Редактор» или «Администратор».
5. В поле «Охват проектов» выберите «Выбранные проекты» и отметьте хотя бы один проект этого тенанта. Для доступа ко всем его проектам выберите «Все проекты».
6. Проверьте выбранные назначения, нажмите «Сохранить доступ» и подтвердите запись. Повторно откройте карточку и сверьте тенант, роль и проекты с сохранёнными значениями.
7. Войдите заново под пользователем, чтобы получить токен с текущей ролью. Откройте разрешённый проект и выполните операцию, которую допускает его системная роль. Для проверки ограничения используйте тестового пользователя с единственным назначением selected: выбранный проект должен открываться, а другой проект — возвращать отказ.

Этот экран редактирует прямые назначения пользователя. Доступ через группы тенанта проверяйте в разделе «Тенанты». При автоматизации передайте в PUT tenant_id, change_reason, system_role и список assignments. Каждое назначение содержит group_id, role, project_scope_mode и allowed_project_ids. Запрос заменяет список назначений: включите в него все назначения, которые нужно сохранить, затем прочитайте результат через GET.

Ограничения:

• Администратор платформы не может отключить собственную учётную запись.
• Нельзя отключить последнего активного администратора платформы или понизить его роль.
• Нельзя удалить последнего администратора группы или понизить его роль, если в группе нет другого администратора.
• Область selected должна включать хотя бы один проект. Все выбранные проекты должны принадлежать назначенной группе.
• Область all не может включать явные идентификаторы проектов.

Определение проекта и операции, зависящие от группы, должны использовать ProjectContext и разрешённую область проекта, а не путь базы данных от пользователя.

Middleware проверки путей

PathValidationMiddleware проверяет поля db_path и source_path в JSON-телах запросов POST, PUT и PATCH.

Правила:

• Пустые строки и байты NUL отклоняются.
• Относительные пути отклоняются, если path_validation_deny_relative=true.
• Компоненты пути нормализуются перед проверкой расположения файла.
• Пути приводятся к фактическому расположению через os.path.realpath().
• Полученный путь должен находиться внутри разрешённого базового каталога.

Разрешённые каталоги определяются по:

• security.path_validation_allowed_base_dirs
• родительским каталогам db_path зарегистрированных проектов
• каталогам source_path зарегистрированных проектов

Поля конфигурации определены в SecurityConfig:

Аутентификация webhook

Проверка webhook находится в src/api/auth/machine/webhook_auth.py. Основная функция проверки — verify_webhook_signature().

Поддерживаемые платформы:

sourcecraft, gitverse и github проверяют подпись HMAC. gitlab сравнивает токен за постоянное время. Проверка возраста использует security.webhook_max_age_seconds, только если запрос содержит непустой заголовок времени поддерживаемой платформы. Отсутствующий заголовок не отклоняется этой проверкой. Она не ведёт список уже принятых событий и сама по себе не предотвращает повторную отправку в допустимом окне. GitLab не имеет такой проверки времени.

Аудит и события для SIEM

Действия, связанные с авторизацией:

Записи аудита машинного доступа содержат тип и идентификатор субъекта, интерфейс, операцию, ресурс, результат и идентификатор учётных данных. Также могут присутствовать идентификатор сервисной учётной записи, версия контракта, идентификаторы проекта и группы.

Справочник конфигурации

Основные поля текущей конфигурации:

Операционные рекомендации

Для администраторов:

1. Используйте admin только для администрирования платформы.
2. Для повседневной сегрегации предпочитайте роли группы GroupRole и доступ к выбранным проектам.
3. Используйте сервисные учётные записи для CI, ботов, порталов, MCP-клиентов и длительного машинного доступа.
4. Берите шаблоны политики как основу и добавляйте только необходимые scope вызывающей стороны.
5. Выпускайте новые ключи сервисной учётной записи до отзыва старых.
6. Оставляйте загрузку кеша отозванных JWT включённой при запуске приложения.
7. Держите проверку путей и scope API-ключей включёнными в общих средах.

Для разработчиков:

1. Используйте require_permission() или require_role() для проверки доступа пользователей к маршрутам.
2. Используйте require_scope() только когда контракт требует проверки строк scope.
3. Добавляйте новые маршруты машинного доступа в API_ROUTE_SCOPE_MAP или MCP_ROUTE_SCOPE_MAP.
4. Сохраняйте согласованность REST/MCP через общие сервисы, без дублирования логики авторизации.
5. Никогда не авторизуйте операции, зависящие от группы, по переданному пользователем db_path.
6. Для изменяющих состояние маршрутов локального плагина требуйте именованного исполнителя и подтверждение задачи.
7. Не записывайте в журналы Bearer-токены, API-ключи, секреты сервисных учётных записей и webhook или исходные запросы к модели.

Связанные документы

• Обзор корпоративной безопасности
• Интеграция OAuth2/OIDC и LDAP/AD
• Интеграция с SIEM
• Защита данных с помощью DLP
• Справочник REST API

Версия: 3.0 | Май 2026