Authentication model

This document covers the additions TokenTimer Enterprise makes to the Core authentication model. The Core admin bootstrap, invitation flow, local password rules, and CSRF behaviour are unchanged; see self-hosted authentication.

CSRF token for scripted API calls

Core CSRF protection (double-submit cookie, always on) applies here unchanged, including for CLM endpoints such as agent bootstrap-token creation. The dashboard attaches the token automatically; a script or CI job driving the API directly with a session cookie must fetch a token from GET /api/csrf-token first and send it back as an X-CSRF-Token header on every POST/PUT/PATCH/DELETE. Machine-token routes (executor events, agent protocol) are exempt and need no CSRF token.

What enterprise adds

Capability	Status
OIDC sign-in	Configurable per deployment
SAML 2.0 sign-in	Configurable per deployment
Group to role mapping (admin UI)	Configurable per deployment
Stable identity across email rename	Always on once SSO is configured
Cross-provider account merge	Controlled by global/per-provider allow auto-link policy
auth_method = 'sso' accounts	Always on once SSO is configured
License-gated SSO settings UI	Always on
Audit log of every login and sync	Always on

Local password sign-in still works in parallel with SSO. For an SSO-only install with no local admin fallback, use Mode 2.

Admin bootstrap with SSO

Two boot modes are supported.

Mode 1: Local admin first, SSO second (default)

This is the recommended mode. You keep emergency access through a locally-managed admin password even if the IdP is down.

1. Set ADMIN_EMAIL / ADMIN_PASSWORD in .env.
2. Start the stack. The Core bootstrap creates the admin user with auth_method='local'.
3. Sign in, open System Settings → Manage SSO providers to configure SSO.
4. Optionally remove ADMIN_PASSWORD from .env and restart. The account stays usable; you can reset it later via DB if needed.

Mode 2: SSO only

When all administrators are managed via the IdP and you want no local fallback account. Use a fresh deployment without local accounts: disabling bootstrap does not disable password sign-in or remove existing local accounts.

Precondition: provision a valid license through TT_LICENSE_KEY or a mounted TT_LICENSE_PATH before the first sign-in. For Helm, configure license.create or license.existingSecret. SSO sign-in is refused without a valid effective license, and there is no local administrator to import one through the dashboard in this mode.

1. Set DISABLE_ADMIN_BOOTSTRAP=true (Helm: tokentimer.config.disableAdminBootstrap).
2. Before starting the API, bootstrap the provider through Helm ssoProviders[] or the Compose sso-providers.json manifest. Include its secret references, redirect URLs and config.bootstrap_admin_groups (a comma-separated list of IdP groups). At least one listed group must be emitted in the first administrator's mapped group claim.
3. Start the deployment and sign in through that provider as the first administrator. A matching bootstrap group grants is_admin=TRUE; verify that System Settings is available. You cannot use the SSO admin UI to configure this first login because no administrator is signed in yet.
4. Once logged in, define the rest of your role mappings (workspace managers, viewers, scoped roles) via System Settings → Single Sign-On. The bootstrap shortcut from step 3 can stay for safety, or be removed if your IaC re-applies it on rebuilds.

Changes to the bootstrap manifest or SSO_<SLUG>_* environment variables require a rolling restart of all API pods so every replica loads the same IdP material. After you have administrator access, provider changes made through the admin UI use the HA synchronization described below.

DISABLE_ADMIN_BOOTSTRAP=true also relaxes the ADMIN_EMAIL requirement in the Helm chart so the install does not block on it.

SSO configuration and high availability

TokenTimer Enterprise supports multiple API replicas behind a load balancer for SSO. Saves under Manage SSO providers bump sso_config_version in Postgres so every API replica reloads SAML/OIDC strategies. SAML InResponseTo uses Postgres (saml_request_cache), not ingress stickiness.

Mechanism	What it syncs
Manage SSO providers save	Bumps system_settings.sso_config_version. Every API pod reloads SAML/OIDC strategies within SSO_CONFIG_SYNC_INTERVAL_MS (default 45s) or on the next /auth/oidc/<slug> / /auth/saml/<slug> request.
Helm / Compose bootstrap	ssoProviders[] manifest and SSO_<SLUG>_* secret env vars on each pod at process start. Changing values in GitOps requires a rolling restart of all API replicas, or one post-deploy save under Manage SSO providers.
Postgres session store	OIDC state, nonce, and PKCE code_verifier (shared across pods).
Postgres saml_request_cache	SAML InResponseTo correlation (shared across pods; ingress stickiness not required; per-provider cache TTL in provider security config, default 3600).

Sign-in readiness: the login page shows SAML/OIDC only when /api/auth/features reports signInReady (strategy registered on that pod), not merely when fields exist in the database. Use status badges and Test under Manage SSO providers (or GET /api/admin/sso/oidc/diagnostics?slug=<slug> with an admin session) when troubleshooting.

IdPs on private networks (blocked_ip)

Outbound IdP fetches (OIDC discovery, token, userinfo, JWKS; SAML metadata) go through an anti-SSRF guard because IdP URLs are admin-editable. By default the guard refuses hosts that resolve to private RFC1918 or link-local addresses; the fetch fails with reason blocked_ip in API logs and in the Test panel (for example discovery_reachable: blocked_ip). No HTTP proxy is involved: the API dials the resolved address directly and ignores HTTP_PROXY/NO_PROXY for these calls.

For an IdP hosted on a private network (internal Keycloak, ADFS, etc.), allow it explicitly:

• SSO_ALLOWED_IDP_CIDRS (Helm: sso.allowedIdpCidrs), a comma-separated IPv4 CIDR allowlist scoped to the IdP subnet. Recommended.
• SSO_ALLOW_PRIVATE_IDP_URLS=true (Helm: sso.allowPrivateIdpUrls), which allows all private ranges. Lab only.

Both are also editable at runtime under System Settings → Single Sign-On → Advanced settings; setting the env var takes precedence and locks the UI field. See Configuration reference for details.

Full env-var tables and IdP guides: Configuration reference, SSO identity provider guides.

Role-based access control

The Core role model separates system admin from workspace roles. Enterprise drives assignment from IdP groups through three layers:

1. System admin: users.is_admin = TRUE. Granted by an idp_group -> role='admin' mapping (workspace_id NULL) or config.bootstrap_admin_groups on the provider row. Sets installation-wide access only; it does not insert a workspace admin membership. Never revoked automatically on mapping removal. Revoke from Workspaces → Members → System admin (or DB).
2. Global non-admin: idp_group -> role='workspace_manager' or 'viewer' with workspace_id NULL. Expands at login time to a membership in every workspace, including ones created after the mapping. New workspaces auto-inherit.
3. Workspace-scoped: idp_group -> role with a specific workspace_id. Targets one workspace.

When a user matches several workspace mappings, the highest role wins per workspace (workspace_manager beats viewer). The SSO admin role is not a workspace role: it never participates in that comparison.

Default workspace after SSO login

After SSO group mappings are applied, the login callback ensures the user has a Default workspace. For the shared Default workspace:

Situation	users.is_admin	Default workspace membership
SSO admin mapping (global)	TRUE	workspace_manager (join existing Default)
Bootstrap / first creator on empty install	TRUE (if mapped)	admin (creates Default)
Second system admin (toggle in Workspaces)	TRUE	unchanged (usually workspace_manager)

So an IdP Admin mapping gives System Settings access, not workspace owner on Default. The bootstrap admin or first provisioner remains the workspace owner unless you change membership outside the product. Multiple workspace owners per workspace (co-owner promote/demote from the Members tab) are planned for a future Core release.

Manual memberships (source='manual') are never overwritten or revoked by SSO.

System-admin expansion (manual toggle or SSO admin grant) adds missing workspace_manager rows on every workspace and may raise viewer to workspace_manager where needed. It never downgrades an existing workspace admin membership and never revokes manual memberships.

See Group mappings for the admin guide.

IdP-only user provisioning

To make your identity system the only way a user gains workspace access, combine two independent controls:

Variable	Closes
SSO_STRICT_MEMBERSHIP_SYNC=true	The automatic path: an unmapped SSO login no longer auto-joins the shared Default workspace as workspace_manager, and is refused with no_group_mapping_matched. Also revokes SSO-derived memberships the IdP stopped asserting.
DISABLE_MANUAL_INVITES=true	The manual path: POST /api/v1/workspaces/:id/members returns 403 MANUAL_INVITES_DISABLED and the dashboard hides the invite controls, so a workspace manager cannot invite someone your identity system does not manage.

Neither one substitutes for the other. With only strict membership sync, managers can still invite arbitrary emails; with only manual invites disabled, an unmapped SSO user still lands in Default workspace as a manager. Set both for a closed installation.

Local admin bootstrap is unaffected by DISABLE_MANUAL_INVITES; use DISABLE_ADMIN_BOOTSTRAP=true (see Mode 2) if you also want no local account at all.

Identity model

Enterprise stores SSO users in two tables:

• users: the same row Core has always had. auth_method is set to 'sso' on first SSO login (from a local account) and never flips afterwards. SSO users have password_hash = 'SSO_NO_PASSWORD'.
• external_identities: one row per (provider, subject_id) pair. Stores email_at_link (raw IdP-asserted email, original casing), display_name_at_link, and last_seen_at. A single TokenTimer user can have many rows (one per IdP they sign in through).

This means:

• A user whose corporate email changes (e.g. marriage, company rebrand) keeps their tokens, audit history, and workspace memberships. The IdP rotates email_at_link on the next login; the underlying user is still keyed by subject_id.
• A user with both SAML (Okta) and OIDC (Azure) accounts asserting the same email is only merged on the first cross-provider login when allow auto-link is enabled (global System Settings → Single Sign-On or per-provider override) AND the IdP confirmed email ownership (OIDC email_verified=true; SAML always counts because the assertion is cert-signed). Otherwise the second-provider login is refused with sso_account_exists_subject_mismatch and an admin has to merge the accounts manually.

See Identity model for the full lifecycle.

Login UX

Deep links

Both /auth/saml/<slug>?next=/dashboard/tokens/123 and /auth/oidc/<slug>?next=/dashboard/tokens/123 land the user on the requested path after a successful flow. The path is sanitised:

• Must start with / and not //.
• Must not contain a URL scheme.
• Max 512 chars.

Anything else falls back to /dashboard. SAML carries the path through RelayState; OIDC stashes it on the session.

Signing out

Signing out of TokenTimer clears the TokenTimer session and ends the identity provider session, using OIDC RP-Initiated Logout against the provider's end_session_endpoint. Both steps matter: the IdP keeps its own SSO cookie, so if only the TokenTimer session were cleared, the next authorization request would be satisfied silently and the user would be signed straight back in without being asked for credentials. That is the behaviour operators expect on shared or kiosk workstations.

The flow is:

1. The dashboard resolves the end-session URL for the current session from GET /api/sso/logout-url (before the local session is destroyed, since the URL is derived from it).
2. The local TokenTimer session is destroyed.
3. The browser is redirected to the IdP end-session URL, which ends the IdP session.

By default TokenTimer does not send post_logout_redirect_uri, so the user finishes on the provider's own signed-out page. This default is deliberate: IdPs match that parameter as an exact string against a registered allowlist and reject anything else, so sending it unconditionally would turn every sign-out into an IdP error page (Keycloak answers 400 Invalid redirect uri).

To return users straight to the TokenTimer login page instead:

1. Add https://<your-tokentimer-host>/login to the client's allowed post-logout redirect URIs (Keycloak: Valid post logout redirect URIs; Entra ID: a regular redirect URI on the app registration's Authentication page, which is what Entra validates post_logout_redirect_uri against; Okta and Auth0: allowed logout URLs).
2. Then set SSO_POST_LOGOUT_REDIRECT=true (Helm sso.postLogoutRedirect).

Enable the flag only after the URI is registered. IdPs differ in how they fail: Keycloak rejects the whole sign-out with 400 Invalid redirect uri, while Entra ID silently ignores the unregistered URI and leaves the user on its generic "You signed out of your account" page.

The request sends id_token_hint when an ID token is available for the session, and client_id only as a fallback when it is not. The two are never sent together: Okta does not accept client_id on its logout endpoint and answers invalid_client, while Keycloak, Entra ID, and Auth0 accept either identifier. With id_token_hint the provider ends the session silently; with only client_id some providers (including Keycloak) first show a "Do you want to log out?" confirmation page.

Provider support for RP-initiated logout:

Provider	Ends the IdP session on sign-out
Keycloak	Yes, via discovery or derived from the realm issuer
Microsoft Entra ID	Yes, via discovery
Okta	Yes, via discovery
Auth0	Yes, via discovery or derived from the tenant issuer
ZITADEL, authentik, AD FS (OIDC)	Yes, via discovery
Google Workspace	No. Publishes no end_session_endpoint
GitLab	No. Publishes no end_session_endpoint
Amazon Cognito	No. Does not implement RP-initiated logout; see below

Providers configured with discovery disabled and manual endpoint URLs keep single logout for Keycloak realm issuers (…/protocol/openid-connect/logout) and Auth0 tenants (…/oidc/logout), whose logout endpoint is derived from the issuer the same way the other endpoints are. For any other issuer, set the provider's end_session_url config key (or leave discovery enabled), otherwise sign-out stays local-only.

Amazon Cognito exposes a proprietary /logout endpoint that takes client_id and logout_uri instead of the standard parameters, and omits it from discovery. You can point TokenTimer at it by setting the provider's end_session_url config key to https://<your-domain>.auth.<region>.amazoncognito.com/logout; TokenTimer then sends client_id and post_logout_redirect_uri. Cognito honours client_id but ignores post_logout_redirect_uri in favour of logout_uri, so the user is signed out of Cognito but is not redirected back automatically.

Sign-out degrades to local-only, with no error shown, when:

• the provider advertises no end_session_endpoint (common for SAML-only IdPs and bare OIDC deployments),
• the session is SAML rather than OIDC (SAML Single Logout is not implemented), or
• SSO_DISABLE_SINGLE_LOGOUT=true (Helm sso.disableSingleLogout) is set.

In every one of those cases the IdP session outlives the TokenTimer session, and the next SSO login will not prompt for credentials. Users must close the browser, or sign out of the IdP separately, to fully end the session.

Failure paths

When SSO fails (signature mismatch, expired assertion, license invalid, network error), the API redirects the browser to /login?error=<reason> and writes a LOGIN_FAILED audit row with the underlying reason and request path. Reasons include:

• saml_failed / oidc_failed: generic strategy callback error.
• oidc_not_ready: OIDC fields are saved but the strategy is not registered on this API pod (check JWKS, discovery reachability, or sso_reload_warnings after save).
• local_account_exists_auto_link_disabled: email matches an existing auth_method='local' user and allow auto-link is off (global System Settings → Single Sign-On, or per-provider override).
• sso_account_exists_subject_mismatch: email matches an existing SSO user already linked to a different (provider, subject_id) on the same provider. Resolved by an admin merge or relink.
• cross_provider_auto_link_disabled: email matches an SSO user linked to a different provider and allow auto-link is off (global System Settings → Single Sign-On, or per-provider override). Sign in with the original provider or enable auto-link.
• email_not_verified_for_link: email-fallback link refused because the OIDC IdP did not assert email_verified=true.
• userinfo_sub_mismatch: the OIDC UserInfo response carried a different sub than the ID Token. The login is hard-refused per OIDC Core 5.3.2.
• license_invalid: license missing, invalid, or past grace.

License gating

The feature:oidc and feature:saml entitlements gate:

• The SSO Providers section of the admin dashboard (hidden when absent).
• PUT /api/admin/sso/providers and related provider CRUD (HTTP 403 / code: "ENTITLEMENT_MISSING").
• The /api/admin/sso-mappings CRUD endpoints (same 403).
• The login UI hides the SSO buttons when no SSO entitlement is available.

When the license lacks feature:oidc or feature:saml, the login UI hides that provider type and admin writes to matching providers return HTTP 403. Bootstrap fields can still register a strategy if present, but operators should align license entitlements with the providers they enable.

Audit log

Every SSO login emits a structured LOGIN_SUCCESS audit row with:

• method: saml or oidc.
• new_user, link_created, previous_auth_method: identity lifecycle deltas.
• subject_id: the IdP subject used as the stable identifier.
• idp_groups_seen: the number of groups asserted by the IdP.
• idp_groups_sample: up to 20 raw group values parsed from the assertion (useful when debugging Entra object IDs vs display names).
• matched_groups: the lowercased array of IdP groups that matched a sso_group_role_mappings row.
• matched_groups_count: scalar of the above for dashboards.
• is_admin_resolved: whether the current login matched a global role='admin' mapping.
• effective_system_admin: whether the user is treated as a system admin for this login (current mapping match or durable SSO grant / is_admin_manual).
• is_admin_after_login: users.is_admin after resolution and user refresh (use to confirm promotion reached the session source row).
• admin_mapping_matched: same boolean as is_admin_resolved; true when an IdP group matched a global admin mapping on this login.
• admin_granted: whether users.is_admin flipped from false to true during this login.
• configured_admin_idp_groups: admin mapping values configured for this provider (from sso_group_role_mappings, global admin rows only).
• workspace_grants_count / workspace_revocations_count: number of membership changes applied.

Each applied membership change additionally emits one MEMBERSHIP_SYNCED_FROM_SSO row with change (created / role_changed / revoked), previous_role (on revoke), and the same matched_groups.

LOGIN_FAILED rows are written for every callback that does not produce a session, including license failures.