Configure OAuth and LDAP identity

OAuth and LDAP authenticate a person against an external identity source. CodeGraph still owns the local user record, role, permissions, project scope, session, audit events, and revocation behavior. An identity-provider group becomes a CodeGraph permission through the approved mapping.

Choose the integration

Use OAuth/OIDC when the provider supports a browser authorization-code flow and centrally managed client registration. Use LDAP or Active Directory when directory bind and group lookup are the approved customer pattern. A deployment can configure both, but each route must have an owner, tested failure mode, and recovery path.

Typed configuration lives in src/api/config.py. Provider and directory implementations live in src/api/auth/providers/oauth.py and src/api/auth/providers/ldap_auth.py.

Current routes

The authenticated application exposes these identity operations under /api/v1/auth:

The route implementation is src/api/routers/auth_suite/auth_external_routes.py. Use deployed OpenAPI for exact payloads and response models.

Configure OAuth

The current typed provider set includes GitHub, Google, GitLab, Keycloak, SourceCraft, and GitVerse. A provider is usable only when enabled and supplied with the required client details. Configure:

• client ID and secret through customer-approved secret references;
• exact redirect URI generated for the deployed public origin;
• authorize, token, and user-info endpoints when the provider needs overrides;
• least-privilege scopes required for identity only;
• TLS trust, proxy, timeout, and outbound allowlist;
• account-linking and deprovisioning ownership.

Register the callback URI exactly. Do not use wildcard redirects, publish client secrets, or allow arbitrary caller-provided callback destinations.

Validate OAuth

The start flow creates a signed or stored one-time state value. The callback must consume the same state and redirect context before exchanging the authorization code.

For each enabled provider:

1. confirm it appears in /api/v1/auth/oauth/providers;
2. start login from the deployed origin;
3. inspect the provider consent request and scopes;
4. complete the callback once and confirm state replay is rejected;
5. confirm the expected local user and least-privilege role;
6. verify logout, session expiry, disablement, and audit events;
7. test a disabled or misconfigured provider without exposing secrets.

Browser success alone is insufficient; verify the resulting CodeGraph authorization boundary.

Configure LDAP

LDAP settings include enabled state, server, port, TLS choice, base DN, user and group search bases, bind identity, bind secret, object classes, identity attributes, membership attribute, and role mapping. Prefer ldaps:// or another customer-approved protected transport across trust boundaries.

The optional ldap3 package must be installed for the authenticator to be available. When LDAP is configured but ldap3 is missing, /api/v1/auth/ldap/status reports degraded availability; the system must not pretend that directory authentication works.

Use a least-privilege bind identity. Never log submitted passwords, bind secrets, raw access tokens, or full directory entries.

Map roles and manage lifecycle

Group-to-role mapping resolves directory groups to the local viewer, analyst, reviewer, or admin role. Review ambiguous and multi-group membership explicitly; do not depend on incidental directory ordering for privilege selection.

Test joiner, mover, and leaver cases:

• first login and local user creation;
• changed name or email without privilege escalation;
• group removal and role reduction;
• disabled provider or directory account;
• existing sessions and API keys after deprovisioning;
• emergency local administrator access under customer policy.

See RBAC for the permission contract after authentication.

Failure and recovery

Distinguish provider unavailability, invalid state, code exchange failure, TLS or DNS failure, directory bind failure, user search failure, group lookup failure, missing dependency, and local database error. Preserve a secret-free request or correlation ID with the failure.

Do not silently fall back from an enterprise identity method to anonymous or over-privileged local access. If break-glass access is approved, make it time-bound, separately credentialed, audited, and reviewed after recovery.

Acceptance evidence

Record provider or directory identity, effective config digest without secrets, TLS boundary, positive and negative login results, state replay rejection, role mapping, deprovisioning behavior, rate-limit behavior, audit events, failure recovery, and the exact release revision. Repeat the checks after route, provider, dependency, role, or session-policy changes.