Configure OAuth and LDAP identity

Login through an OAuth provider or LDAP links an external identity to a local user. CodeGraph manages the local role, permissions, project access, sessions, and audit events. An administrator assigns local roles and project access using RBAC.

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.

You need access to the API process environment, an application registered with the provider or a directory search account. Prepare the public CodeGraph HTTPS origin and a separate test account.

Current routes

The application exposes these login operations under /api/v1/auth:

Use the deployed API OpenAPI at /api/docs for exact request and response fields.

Configure OAuth

The standard API environment configuration supports GitHub, Google, SourceCraft and GitVerse. Set the variables for your provider:

1. Register an application with the provider. Use the public API HTTPS origin and /api/v1/auth/oauth/{provider}/callback for the redirect URI. Replace {provider} with github, google, sourcecraft or gitverse. For an API at https://codegraph.example.org, the GitHub redirect is https://codegraph.example.org/api/v1/auth/oauth/github/callback.
2. Supply the client ID and secret to the API process environment through your organization’s secret store. Source installations also read .env from the working directory; protect that file and exclude it from Git.
3. Apply the environment by restarting the API using the deployment guide.
4. Request GET /api/v1/auth/oauth/providers. Find the selected provider with enabled: true and a nonempty authorize_url. Open that URL to test login.

The list also includes disabled entries. GitLab and Keycloak appear in the provider catalog, but their standard API environment configuration is incomplete in this version. Their connection workflows are excluded from this guide.

Validate OAuth

The start flow creates a one-time state value. The callback consumes it, verifies the provider binding, and uses the stored redirect URI when exchanging the authorization code.

For each enabled provider:

1. confirm enabled: true and authorize_url 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.

After login, verify the operations and projects available to the local CodeGraph user.

Configure LDAP

Set these variables in the API process environment:

In LDAP_SERVER, ldaps:// selects TLS and default port 636; ldap:// selects port 389. An explicit port after the colon overrides the default. Agree on the protected connection with the directory owner.

Restart the API after applying the environment and request GET /api/v1/auth/ldap/status. Expect enabled: true, available: true and connected: true. Then test POST /api/v1/auth/ldap with username and password fields.

The Python project dependencies include ldap3. If the status reports available: false and a missing-library message, install the dependencies for the same CodeGraph version in the API environment and repeat the check. Give the search account least-privilege access; transfer passwords through protected channels and keep them in your secret store.

Map roles and manage lifecycle

When provisioning a user, the group mapper selects the local viewer, analyst, reviewer, or admin role. The current mapper checks matches in the order admin, reviewer, analyst, viewer; multiple matches select the most privileged role. No matching group returns analyst. The standard API environment loads an empty group mapping in this version, so a new LDAP user receives analyst. Assign working roles and projects in the user management interface described in RBAC. Startup configuration of group role_mapping is excluded from this guide.

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. An existing user retains the local role on subsequent login. After an external group change, an administrator updates that role in CodeGraph and checks access with newly issued and existing tokens. Configure token lifetimes and verify the procedure for revoking existing sessions.

Check role mapping locally

From the CodeGraph source root with the project’s Python environment, save this example as check_ldap_roles.py and run python check_ldap_roles.py. It uses synthetic group names and calls the same mapper as LDAP login. The check runs locally without a directory connection or user credentials.

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")

Expected output: LDAP role mapping: 4 cases passed. The four cases cover an unmatched user, a viewer, overlapping reviewer/viewer groups, and overlapping administrator/reviewer groups. The example demonstrates the algorithm on a local LDAPConfig object; it does not change the running API configuration.

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.