Skip to main content
Version: next

OIDC SSO quickstart

Configure one OpenID Connect identity provider (IdP), then enable sign-in.

Prerequisites:

  • The Enterprise delivery tarball pulled from the registry, which contains the Helm examples and Compose files referenced below. See Registry access.
  • An OIDC application registered in your IdP, with its issuer URL, client ID, and client secret at hand.
  • The shared prerequisites in the SSO overview.

Helm​

  1. Copy helm/examples/values-sso-basic-oidc.yaml (from the delivery) into your values file.
  2. Set tokentimer.config.apiUrl and baseUrl to your public origins.
  3. Create the Kubernetes Secret named in the example (entra-oidc) with key SSO_ENTRA_OIDC_CLIENT_SECRET exactly as shown in that file.
  4. helm upgrade the release using that values file (the example includes bootstrap mount and envFrom wiring).

SSO encryption keyring: by default the chart creates <release>-enterprise-secrets with SSO_SECRETS_KEYRING (auto-generated on first install, preserved on upgrade). To create it yourself, use the JSON format and kubectl steps in the Configuration reference (Keyring JSON format). That Secret holds AES keys for UI-managed secrets; it is not stored in Postgres.

Compose​

Run these steps from the compose/ directory of the delivery.

  1. cd compose
  2. cp sso-providers.basic-oidc.example.json sso-providers.json
  3. Generate the SSO keyring: see the keyring section of the Compose SSO README (compose/sso-providers.README.md in the delivery).
  4. Merge .env.sso-basic.example into .env and fill the SSO_* secret values (rename keys if your slug differs).
  5. docker compose -f docker-compose.yml -f docker-compose.sso.yml up -d

Manifest shape, env prefix rules, and advanced Compose setup are covered in the Compose SSO README in the delivery.

Dashboard​

  1. Sign in as admin, open System Settings → Manage SSO providers, run the OIDC wizard.
  2. Copy the callback URL shown (/auth/oidc/<slug>/callback) into your IdP redirect URIs.
  3. Run Test, map at least one admin group under System Settings → Single Sign-On, then Enable.

Callback URL​

Register exactly:

https://<api-host>/auth/oidc/<slug>/callback

For deeper tuning (endpoint overrides, claim paths, private IdP URLs), see the Configuration reference and Claim mapping.