Enterprise SSO (OIDC)
Enterprise SSO lets your organization's members sign in to Zynth Auth through your own OpenID Connect identity provider (Okta, Microsoft Entra ID, Keycloak, Auth0, …) instead of — or alongside — passwords, passkeys, and social login.
Availability: enterprise federation is feature-flagged per deployment. If the Enterprise SSO settings page reports it is not enabled, ask your platform operator (self-hosted: see the internal deployment runbook) to enable it.
How it works
- A user picks Sign in with enterprise SSO on the sign-in page and enters your organization identifier.
- Zynth Auth redirects the browser to your IdP (authorization-code flow with PKCE).
- Your IdP authenticates the user and returns a signed
id_token, which Zynth Auth validates strictly — signature against your IdP's published keys, issuer, audience, expiry, and a one-time nonce. - The user lands back in Zynth Auth with a normal session. If they have MFA enrolled in Zynth Auth, the MFA challenge still applies — federation never bypasses a second factor.
Configuring a connection
On Settings → Organization → Enterprise SSO (requires the tenant:manage permission):
| Field | Meaning |
|---|---|
| Issuer URL | Your IdP's issuer, https:// only. Endpoints are discovered from <issuer>/.well-known/openid-configuration, and the document's issuer must match exactly. |
| Client ID / secret | The app registration at your IdP. The secret is stored encrypted and never shown again; leave it blank for a public (PKCE-only) client. |
| Scopes | Defaults to openid email profile. |
| Email / groups claim | Which id_token claims carry the user's email and directory groups. |
| Group → role mapping | Maps IdP groups to membership roles, one group = role per line; first matching group wins, re-applied on every sign-in. |
| Default role | Role for just-in-time-provisioned users when no group maps. |
| Just-in-time provisioning | When on, unknown subjects asserted by your IdP get a workforce account and membership automatically. When off, only existing members can sign in. |
| Connection enabled | Master switch for the connection — configured-but-disabled serves no logins. |
Register the callback URL at your IdP:
https://<your-zynth-auth-host>/api/v1/auth/sso/oidc/callback.
Use Test connection after saving — it fetches your IdP's discovery document and verifies the issuer, so you can prove reachability before enabling the connection.
Who can sign in with SSO
- Existing members of your organization — matched by the email your IdP asserts, linked on first SSO sign-in. Your IdP can only claim accounts that are already members of your organization — never users who belong only to other tenants.
- New people — only when just-in-time provisioning is on. They're created as workforce accounts with the mapped (or default) role.
Failure behavior (fail-closed)
Sign-in fails safely — with one generic error, never a diagnostic oracle — when the state
or nonce doesn't match, the id_token signature/issuer/audience/expiry fails, the signing
key can't be found after a refresh (key rotation is otherwise handled automatically), or
the connection is disabled. Connection configuration changes are audited and raise an alert
in the Command Center every time.
Requiring SSO for your organization
Once your connection is enabled and tested, the Enforcement tab lets you require SSO: members can then sign in only through your IdP — password, sign-in-link, passkey, and social sign-in are refused. Organization owners keep password and passkey sign-in as a break-glass path (every use is audited and alerts your security view), so a broken IdP can never lock you out. The policy can only be enabled while a connection is enabled, and you can lift it at any time. If your IdP supports back-channel logout, signing a user out at the IdP ends all their Zynth Auth sessions immediately.