Skip to main content
Version: next

SAML SSO quickstart

Configure SAML from IdP metadata (URL, paste, or upload). TokenTimer picks HTTP-Redirect for AuthnRequest when available.

Prerequisites:

  • The Enterprise delivery tarball pulled from the registry, which contains the Helm examples and Compose files referenced below. See Registry access.
  • A SAML application registered in your identity provider (IdP), with its metadata (URL or XML) at hand.
  • The shared prerequisites in the SSO overview.

Helm​

  1. Copy helm/examples/values-sso-basic-saml.yaml (from the delivery) into your values file.
  2. Set entryPoint, issuer, and your IdP signing cert via the Secret named in the example (keycloak-saml-idp) with key SSO_KEYCLOAK_SAML_CERT exactly as shown.
  3. helm upgrade the release using that values file (the example includes bootstrap mount and envFrom wiring).

For encrypted assertions or signed AuthnRequests, see helm/examples/values-sso-full-reference.yaml in the delivery.

SSO encryption keyring: by default the chart auto-creates <release>-enterprise-secrets. For a manual Secret or sso.secretsKeyring, follow the Configuration reference (Keyring JSON format). Key material lives only in Kubernetes/env, not in Postgres.

Compose​

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

  1. cd compose
  2. cp sso-providers.basic-saml.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 (paste IdP cert PEM into SSO_KEYCLOAK_SAML_CERT for the bundled example slug).
  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. System Settings → Manage SSO providers, add SAML provider, paste or fetch metadata XML.
  2. Copy the SP metadata URL (/auth/saml/<slug>/metadata) into your IdP.
  3. Copy the ACS callback URL (/auth/saml/<slug>/callback).
  4. Run Test, then Enable.

Verify​

  1. GET /api/auth/features returns your slug in providers.saml[] with signInReady: true.
  2. Use the provider button on the login page.

Troubleshooting​

SymptomLikely causeFix
No provider button on loginLicense missing feature:saml, provider disabled, or signInReady: falseFix license (System Settings → License); enable provider and run Test under Manage SSO providers; confirm slug in GET /api/auth/features providers.saml[]

IdP-initiated SSO​

Not supported in v1 (InResponseTo is always required). Use SP-initiated login from the TokenTimer login page.

For SLO, claim mapping, and restricted networks, see the Authentication model and SSO identity provider guides.