Skip to main content
Version: 0.17

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.

Choose one configuration method below. Register the exact callback shown for your API origin and provider slug in the IdP before testing sign-in. Keep a verified local administrator while setting up SSO, or provision the license, provider manifest, secrets, and verified bootstrap-admin group before first startup for SSO-only mode.

Helm​

  1. Merge helm/examples/values-sso-basic-saml.yaml (from the delivery) into your existing deployment values; retain database, URLs, license mounts, and other required settings.
  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 Keyring JSON format. Key material lives only in Kubernetes/env, not in Postgres.

Compose​

Start at the extracted delivery root, then enter compose/.

  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. Confirm GET /api/auth/features lists the slug under the chosen protocol with signInReady: true.
  2. In a new private browser window, start login from TokenTimer and complete the IdP exchange.
  3. Confirm the expected workspace role and, for the first operator, system-administrator access. A provider Test checks configuration/transport; it does not prove the resulting user grants.
  4. Keep the existing administrator session until the new login and recovery access are verified.

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.