Настройка OAuth и LDAP

Вход через OAuth-провайдера или LDAP связывает внешнюю учётную запись с локальным пользователем. CodeGraph управляет его ролью, разрешениями, доступом к проектам, сессией и событиями аудита. Администратор назначает локальные роли и доступ к проектам по правилам RBAC.

Выбор интеграции

Выберите вход через OAuth-провайдера, если организация использует браузерный вход и регистрацию клиентов у провайдера. LDAP или Active Directory подходят для проверки учётной записи и поиска групп в корпоративном каталоге. Для каждого включённого способа назначьте ответственного и проверьте обработку ошибок и восстановление.

Для настройки нужны права на окружение API, регистрация приложения у провайдера или учётная запись поиска в каталоге. Подготовьте публичный HTTPS-адрес CodeGraph и отдельную тестовую учётную запись.

Актуальные маршруты

Приложение публикует операции входа под /api/v1/auth:

Точные поля запросов и ответов приведены в OpenAPI развёрнутого API по адресу /api/docs.

Настройка OAuth

Штатная настройка через окружение API включает GitHub, Google, SourceCraft и GitVerse. Задайте параметры выбранного провайдера:

1. Зарегистрируйте приложение у выбранного провайдера. В адресе возврата используйте публичный HTTPS-адрес API и путь /api/v1/auth/oauth/{provider}/callback, заменив {provider} на github, google, sourcecraft или gitverse. Например, для API https://codegraph.example.org адрес GitHub — https://codegraph.example.org/api/v1/auth/oauth/github/callback.
2. Передайте идентификатор и секрет в окружение процесса API через принятое в организации хранилище секретов. При запуске из исходников API также читает .env из рабочего каталога; защитите этот файл и исключите его из Git.
3. Примените настройки штатным перезапуском API по руководству развёртывания.
4. Запросите GET /api/v1/auth/oauth/providers. Найдите запись выбранного провайдера с enabled: true и непустым authorize_url. Перейдите по этому адресу для тестового входа.

Список возвращает и отключённые записи. GitLab и Keycloak присутствуют в справочнике провайдеров, но их настройка через штатное окружение API в этой версии не завершена. Сценарии их подключения исключены из этой инструкции.

Проверка OAuth

При начале входа создаётся одноразовый state. Обработчик возврата проверяет его привязку к провайдеру и использует сохранённый адрес возврата при обмене кода авторизации.

Для каждого включённого провайдера:

1. подтвердите enabled: true и authorize_url в /api/v1/auth/oauth/providers;
2. начните вход с адреса развёрнутой системы;
3. проверьте согласие пользователя и запрошенные разрешения;
4. завершите вход один раз и убедитесь, что повторное использование state отклоняется;
5. проверьте локального пользователя и выданную роль;
6. проверьте выход, истечение сессии, отключение пользователя и события аудита;
7. проверьте отказ отключённого или неверно настроенного провайдера без раскрытия секретов.

После входа проверьте фактически доступные операции и проекты CodeGraph.

Настройка LDAP

Задайте переменные окружения процесса API:

В LDAP_SERVER префикс ldaps:// выбирает TLS и порт 636 по умолчанию; ldap:// выбирает порт 389. Явный порт после двоеточия заменяет значение по умолчанию. Согласуйте защищённое соединение с владельцем каталога.

После применения окружения перезапустите API и запросите GET /api/v1/auth/ldap/status. Ожидайте enabled: true, available: true и connected: true. Затем выполните тестовый вход через POST /api/v1/auth/ldap с полями username и password.

Пакет ldap3 входит в зависимости Python-проекта. Если статус показывает available: false и сообщение об отсутствии ldap3, установите зависимости той же версии CodeGraph в окружение API и повторите проверку. Учётная запись поиска должна иметь минимальные права; пароли передавайте через защищённые каналы и храните в хранилище секретов.

Сопоставление ролей и управление доступом

При создании пользователя метод сопоставления групп выбирает локальную роль viewer, analyst, reviewer или admin. Текущая реализация проверяет совпадения в порядке admin, reviewer, analyst, viewer: при нескольких совпадениях выбирается наиболее привилегированная роль. Если совпадений нет, возвращается analyst. Штатное окружение API в этой версии загружает пустое сопоставление групп, поэтому новый LDAP-пользователь получает analyst. Назначайте рабочие роли и проекты в интерфейсе управления пользователями по RBAC. Настройка группового role_mapping при запуске исключена из этой инструкции.

Проверьте создание учётной записи, изменение доступа и отключение пользователя:

• первый вход и создание локального пользователя;
• смену имени или email без повышения прав;
• удаление из группы и снижение роли;
• отключение провайдера или учётной записи каталога;
• существующие сессии и API-ключи после отзыва доступа;
• аварийный локальный доступ администратора по политике организации.

Контракт разрешений после входа описан в RBAC. При повторном входе существующий пользователь сохраняет локальную роль. После изменения внешней группы администратор обновляет её в CodeGraph и проверяет доступ по новым и уже выданным токенам. Настройте срок действия токенов и проверьте процедуру отзыва существующих сессий.

Локальная проверка сопоставления ролей

Из корня исходников CodeGraph в Python-окружении проекта сохраните пример как check_ldap_roles.py и выполните python check_ldap_roles.py. Он использует условные названия групп и вызывает тот же метод, что и вход через LDAP. Проверка выполняется локально, без подключения к каталогу и учётных данных пользователей.

from src.api.config import LDAPConfig
from src.api.auth.providers.ldap_auth import LDAPAuthenticator

config = LDAPConfig(role_mapping={
    "codegraph-admins": "admin",
    "codegraph-reviewers": "reviewer",
    "codegraph-viewers": "viewer",
})
authenticator = LDAPAuthenticator(config)

cases = [
    ([], "analyst"),
    (["codegraph-viewers"], "viewer"),
    (["codegraph-viewers", "codegraph-reviewers"], "reviewer"),
    (["codegraph-reviewers", "codegraph-admins"], "admin"),
]
for groups, expected in cases:
    actual = authenticator.map_groups_to_role(groups)
    assert actual == expected, (groups, actual, expected)
print("LDAP role mapping: 4 cases passed")

Ожидаемый результат: LDAP role mapping: 4 cases passed. Проверка охватывает пользователя без сопоставленной группы, читателя, участника групп читателя и рецензента, а также участника групп администратора и рецензента. Пример показывает алгоритм на локальном объекте LDAPConfig; настройки работающего API он не изменяет.

Ошибка и восстановление

Различайте недоступность провайдера, неверный state, ошибки обмена кода, TLS и DNS, отказ подключения к каталогу, ошибки поиска пользователя и групп, отсутствие зависимости и ошибку локальной БД. Сохраняйте идентификатор запроса для сопоставления событий.

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

Доказательства приёмки

Сохраните название провайдера или каталога, хеш действующей конфигурации без секретов, результаты проверки TLS, успешного и неуспешного входа, отказа при повторном state, выдачи ролей и отзыва доступа. Проверьте ограничение частоты запросов, события аудита и восстановление. Укажите точную ревизию CodeGraph. Повторяйте проверки после изменения маршрутов, провайдера, зависимости, роли или правил сессии.