Skip to main content

Federated Login (SSO / OIDC)

Starting from v1.8.0, RAG-DocBot supports multi-provider OpenID Connect (OIDC) login with Authorization Code + PKCE (S256). Users can log in via your organisation's identity provider instead of (or in addition to) a local password.

For the full technical reference see AUTH.md in the RAG-DocBot source repository.

Supported Identity Providers​

Pre-tested integrations are available for:

  • Microsoft Entra ID (formerly Azure AD)
  • Google Workspace
  • Keycloak
  • Any standards-compliant OIDC IdP

How It Works​

  1. An admin configures a provider in the admin UI. The configuration is stored in the oidc_providers Postgres table.
  2. Users visit the login page and select their provider. The browser is redirected to the IdP for authentication.
  3. On successful login, RAG-DocBot exchanges the authorisation code for an ID token (PKCE S256 prevents code interception).
  4. If the user doesn't exist locally, they are provisioned automatically (JIT provisioning) with the role and groups derived from the IdP claims.
  5. Group membership from IdP claims is synced on first login. After provisioning, role and group management is handled within RAG-DocBot (not overwritten on every login).

Configuring a Provider​

  1. Log in as an admin and navigate to Settings → SSO Providers.

  2. Click Add Provider and fill in the fields:

    • Name — a short identifier (e.g. entra, google)
    • Display name — shown on the login page button
    • Client ID — from your IdP's app registration
    • Client secret — stored encrypted at rest; never returned by the API
    • Discovery URL — the IdP's .well-known/openid-configuration endpoint
    • Redirect URI — must match what is registered with the IdP (e.g. https://docbot.example.com/api/auth/oidc/entra/callback)
    • Scopes — space-separated (default: openid email profile)
    • Admin groups — IdP group names whose members are auto-promoted to the admin role on first login

  3. Click Test to verify the provider configuration is reachable before saving.

Via Environment Variables (fallback / bootstrap)​

Env-var configuration is used as a fallback when the oidc_providers table is empty. This is useful for scripted deployments or bootstrapping a fresh instance.

OIDC_PROVIDERS=entra,google

OIDC_ENTRA_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OIDC_ENTRA_DISCOVERY_URL=https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration
OIDC_ENTRA_REDIRECT_URI=https://docbot.example.com/api/auth/oidc/entra/callback
OIDC_ENTRA_SCOPES=openid email profile
OIDC_ENTRA_ADMIN_GROUPS=DocBot-Admins

OIDC_GOOGLE_CLIENT_ID=<google-client-id>.apps.googleusercontent.com
OIDC_GOOGLE_DISCOVERY_URL=https://accounts.google.com/.well-known/openid-configuration
OIDC_GOOGLE_REDIRECT_URI=https://docbot.example.com/api/auth/oidc/google/callback

Client secrets must be supplied as Docker secrets, not as plain env vars:

echo "<entra-client-secret>"  | docker secret create oidc_entra_client_secret -
echo "<google-client-secret>" | docker secret create oidc_google_client_secret -

Once a provider is saved via the admin UI, the oidc_providers table takes precedence and env-var config is ignored for that provider.

Admin API​

EndpointDescription
GET /api/admin/oidc/providersList all configured providers
POST /api/admin/oidc/providersCreate a new provider
GET /api/admin/oidc/providers/{id}Get provider details (client_secret is never returned; secret_set: bool indicates whether it's configured)
PATCH /api/admin/oidc/providers/{id}Update a provider
DELETE /api/admin/oidc/providers/{id}Delete a provider
POST /api/admin/oidc/providers/{id}/testTest the provider's discovery URL and connectivity

User-Facing Endpoints​

EndpointDescription
GET /api/auth/oidc/providersList providers visible on the login page
GET /api/auth/oidc/{provider_id}/loginInitiate OIDC login (redirects to IdP)
GET /api/auth/oidc/{provider_id}/callbackOIDC callback handler (handles IdP redirect)

JIT Provisioning & Group Sync​

  • Users are created automatically on their first successful OIDC login.
  • The user's role and groups are set from IdP claims on first login only. Subsequent logins do not overwrite role or group assignments managed within RAG-DocBot (see v1.8.0 changelog for the fix to issue #328).
  • Use OIDC_<NAME>_ADMIN_GROUPS (env) or the Admin groups field in the UI to automatically promote members of specific IdP groups to the admin role on provisioning.

Security Notes​

  • PKCE with S256 challenge method is always used — plain PKCE is not supported.
  • client_secret is encrypted at rest using the MFA_ENCRYPTION_KEY (Fernet). It is never returned by any API endpoint. The secret_set: bool field indicates whether a secret has been configured.
  • OIDC-only users have a NULL hashed_password in the database — they cannot log in via the username/password endpoint.