Skip to main content
Version: 0.15

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 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.