SSO, Passwordless Login & SCIM

Three ways in that never ask your instance for a password: single sign-on (SSO) through your own identity provider, single-use sign-in links sent by email, and sign-in with a passkey.

What It Does

Each of these lets an existing user sign in without typing a local password, but they solve different problems, and by default none of them creates accounts.

If something here is not working as you expect, start with When something goes wrong.

Configuring Your IdP

SSO configuration lives in the database (a SecuritySetting row keyed sso_config), not in an environment file. The OIDC client secret is stored encrypted at rest (AES-256-GCM, the shared key ring) and is never returned to any caller — reads report only whether a secret is set. The config endpoints are gated at the route on the manage_security permission, and the controller checks it again; the gateway injects the authenticated, signed x-user after validating the session. Writing the config additionally requires a fresh sudo step-up (SUDO_REQUIRED otherwise), because repointing sign-in at a different IdP is a security-boundary change.

The write body carries the fields below. Validation is protocol-aware — only the active protocol has to be complete, and the other protocol’s fields are kept untouched so you can switch back. When enabled is true and protocol is oidc, issuer must be an https URL, clientId is required, and a client secret must be supplied or already stored; when it is saml, the IdP entity ID, SSO URL and at least one signing certificate are required. A failed check rejects the save with 400. A save is audit-logged as SSO_CONFIG_UPDATED.

• enabled, protocol (oidc or saml) and preset (your provider, which only labels the sign-in button and the setup hints).
• OIDC: issuer, clientId, clientSecret (optional on update — omit it to keep the stored one).
• SAML: saml: { idpEntityId, idpSsoUrl, idpCerts }; certificates are kept when not re-supplied, and several are allowed during a rotation.
• jit — the just-in-time provisioning block (off by default): allowed email domains and a non-privileged default role or group.
• mfaAcrValues — optional list of authentication-context values your IdP sends after MFA that should count as a proven second factor.

At your IdP, register your instance as an OIDC confidential client and grant the scopes openid email profile (the values your instance requests). For the redirect URI (OIDC) or the Entity ID and ACS URL (SAML), copy the exact values shown in Security Settings → SSO (OIDC / SAML) rather than typing them — they are built from your instance’s own address and end in /auth/sso/callback and /auth/sso/saml/acs. The OIDC issuer you enter must be the one whose /.well-known/openid-configuration discovery document echoes the same issuer back — a mismatch is rejected at discovery time.

What To Set On The OIDC Client At Your IdP

• Flow: authorization code (response_type=code). No implicit or hybrid flow is used.
• Client authentication at the token endpoint: client_secret_post. The client id and client secret are sent in the form body of the token request. client_secret_basic (an Authorization header) and private_key_jwt are not used, so the client at your IdP must allow client_secret_post.
• PKCE is not sent. The authorize request carries no code_challenge and the token request no code_verifier. If your IdP requires PKCE for this client, the sign-in will fail; set PKCE to optional for it. The exchange is protected by the client secret, state and nonce.
• ID-token signing algorithm: RS256. A token signed with any other algorithm is refused.
• Discovery must be reachable. Your instance reads /.well-known/openid-configuration under the issuer and the key set it names, and keeps each for up to one hour. Those addresses and the token endpoint must be public: one that resolves to a private, loopback or cloud-metadata address is refused, and a redirect from any of them is not followed.

The Login Exchange

The browser-facing flow is owned by the gateway, which binds the run to a signed, short-lived sso_flow cookie; the OIDC and SAML logic and session issuance live in the identity service. Both protocols finish in the same place, with one of three outcomes: a session, a parked continuation (a second factor or Terms acceptance is still owed), or a denial.

State, Nonce And The Token Request

• state and nonce are two separate values of 32 random bytes each (base64url), made new for every sign-in.
• Where they are kept. Not on the server. The gateway puts both, with the redirect URI, into a token signed with HS256 under a per-instance secret and valid for 10 minutes, and sets it as the sso_flow cookie: HttpOnly, path /auth/sso, and in production Secure with SameSite=None.
• On return the cookie’s signature and expiry are checked first, then the state in the address must equal the one in the cookie. A missing or expired cookie, or a different state, sends the browser to /login?sso_error=state and no code is exchanged.
• The token request is a form POST from your instance to the IdP’s token endpoint with grant_type=authorization_code, code, redirect_uri, client_id and client_secret in the body (client_secret_post). No PKCE verifier is sent. Only the id_token in the answer is used.

The ID-token verification is where the trust decision is made. Every one of these guards must pass, and an inspector can hold the flow to each:

• Algorithm is pinned to RS256. The token’s own alg header is never trusted; a token presenting any other algorithm is rejected before verification — the classic alg:none / HS256-confusion bypass cannot apply.
• Signature is checked against the IdP’s JWKS by kid, and issuer, audience (your clientId) and expiry are all enforced. An unknown kid triggers exactly one JWKS re-fetch to follow key rotation.
• Nonce must equal the one this flow generated. The value bound to the browser’s signed cookie has to match the token’s nonce claim — the replay/injection binding.
• Email must be present and verified. An email_verified of false is refused, and the email is lower-cased before lookup.
• JIT provisioning is off by default. The email must map to a local user whose status is active. Otherwise the attempt is denied and audited as SSO_LOGIN_DENIED; nothing is created. The one exception is opt-in just-in-time provisioning: when you enable it, an email with no account at all, from an allow-listed domain, is created with your chosen non-privileged default role or group (audited as USER_JIT_PROVISIONED). An existing inactive or offboarded account is never re-opened.

SAML Response Verification

SAML has the same trust decision as the ID-token checks above, made on the response your IdP posts to the ACS URL. Every guard must pass; any failure ends at /login?sso_error=… with no session.

• The assertion itself must be signed by one of the IdP certificates you configured. A signature on the outer response alone is not enough.
• SHA-1 is refused. A response that uses an RSA-SHA1, DSA-SHA1, HMAC-SHA1 or SHA-1 digest algorithm is rejected: SAMLResponse uses a SHA-1 signature/digest; SHA-256 or stronger is required.
• A response containing a DOCTYPE is refused before it is parsed.
• Size. The gateway accepts the ACS form post up to 100 KB, with at most 5 form fields. That limit is on the URL-encoded form, so the usable SAMLResponse is somewhat smaller. The identity service has its own cap of 256 KB on the base64 SAMLResponse, which the gateway limit is reached before. Keep the group and attribute claims your IdP puts in the assertion small.
• InResponseTo is required and single-use. It must equal the request ID bound to this browser’s signed cookie, the request is valid for 10 minutes, and its ID is consumed on first use, so a replayed response fails. This is also why IdP-initiated sign-in is refused.
• Destination and Recipient must be your ACS URL. The response’s Destination, when present, and the Recipient on every bearer SubjectConfirmationData must equal the ACS URL exactly.
• Issuer and audience are pinned. The assertion’s Issuer must equal the IdP entity ID you configured, and the audience must be your instance’s SP entity ID (its metadata URL).
• Expiry is mandatory. The assertion must carry exactly one Conditions element with NotOnOrAfter, and NotOnOrAfter on its bearer SubjectConfirmationData. Clock skew tolerance is 60 seconds.
• The email decides who signs in. The requested NameID format is emailAddress. The email is read from an email attribute (email, mail, the standard emailaddress claim) or, failing that, from the NameID; it is lower-cased and must be a well-formed address.
• No authentication context is requested. Your IdP chooses how the person authenticates. The AuthnContextClassRef it returns is compared against your MFA-satisfying authentication contexts list for privileged accounts.

On the configuration side, the IdP SSO URL must be https, IdP metadata is fetched over https only (8-second timeout, 512 KB cap), and metadata must offer an HTTP-Redirect SingleSignOnService and at least one signing certificate. The service provider is configured with no signing or decryption key of its own, so it does not sign its AuthnRequest and does not accept encrypted assertions: have your IdP send a signed, unencrypted assertion.

Magic-Link Passwordless

A magic link is a JWT carrying { id, email, isMagicLink: true }, signed with the instance JWT_SECRET and valid for 15 minutes. It is a single-purpose email credential, not a session: /validate and /refresh-token both reject an isMagicLink token outright, so a leaked link can only be redeemed at the verify endpoint.

A magic link replaces the password, nothing more. It proves control of the inbox — the first factor — so the same gates as a password sign-in run after it, in the same order: a pending forced password change, then the second factor when MFA is required for that person (a short-lived MFA-challenge token is returned and the client completes /mfa/verify or a passkey), then acceptance of the current Terms. Only when none of those is owed does verify return a session.

The single-use guarantee is not cosmetic: verify atomically claims the token before it loads the user or issues anything, so even a race between two redemptions of the same link cannot mint two sessions, and the link stays consumed even when the outcome is an MFA challenge. A used or expired link reaches the caller as 400 with { error, correlationId }: the identity service answers 401 and the gateway turns that into 400. A completed sign-in is audit-logged as LOGIN_MAGIC_LINK_SUCCESS; the request itself as MAGIC_LINK_REQUESTED.

SMTP Is A Hard Dependency

No link reaches a user unless outgoing mail works. Two things must be in place: SMTP settings (host, user, password — the password is stored encrypted at rest and never returned) configured through POST /api/v1/auth/settings/security, and a sign-in base URL so the link can be built (Zonitix sets your instance’s domain when we provision it; you do not configure it). Verify deliverability first with the SMTP-test endpoint, which sends a real message and returns { success } or a 400 if SMTP is not configured:

Passkey Sign-In

The SIGN IN WITH A PASSKEY button on the sign-in page runs a discoverable-credential (usernameless) WebAuthn ceremony: no username, no password and no MFA-challenge token. The browser offers the passkeys stored for your instance, the authenticator demands user verification (biometric or PIN), and the assertion itself tells the server whose credential it is. Because possession and user verification are both proven in that one gesture, a successful ceremony issues a session that is already MFA-verified — there is no separate second-factor step. It works only for someone who has already added a passkey, and it needs no SMTP and no IdP.

The challenge is stored server-side and consumed on the first verify whatever the outcome, which is what stops a replayed assertion. The account gates a password sign-in applies still run after the ceremony: an active lockout, a non-active status, a pending forced password change and acceptance of the current Terms. A successful sign-in is audit-logged as WEBAUTHN_LOGIN_SUCCESS; an unrecognised credential as WEBAUTHN_LOGIN_UNKNOWN_CRED. The relying-party ID, attestation, user-verification, algorithm, timeout and challenge values are listed under Passkey Parameters.

Rate Limiting

Three gateway limiters cover these paths, all keyed by the true client IP (the address Cloudflare reports, not a spoofable header):

• Sign-in limiter — 20 failed attempts per 15 minutes. Shared by password login, magic-link/verify, accept-terms, sso/login, sso/callback, the SAML ACS and the SAML metadata endpoint. It counts failed responses only, so successful sign-ins never spend from it. Exceeding it returns 429 with Too many authentication attempts. Please try again later.
• Magic-link request limiter — 30 requests per 15 minutes. magic-link/request has its own separate budget that counts every request (it answers with the same success message either way, so a failures-only limiter would never trip). Its 429 reads Too many sign-in link requests from this network. Please try again later.
• Second-factor limiter — 20 failed attempts per 5 minutes. Covers the passkey sign-in endpoints along with the other MFA routes.

All three of these limiters fail closed: if the Redis store is unreachable the request is refused with a 503 rather than allowed through, so a store outage never silently disables brute-force protection. The SCIM limiter below does not: it lets requests through while Redis is down. The full list is on Rate, Size & Time Limits.

SCIM 2.0 Provisioning

SCIM is a standard way for an identity provider to create, update and deactivate accounts in another system as people join, change and leave. An administrator switches it on by generating a token under Security Settings → Provisioning (SCIM) and pasting the base URL and token into the identity provider; from then on the provider pushes changes by itself. Steps: Push users with SCIM. The rest of this section is the protocol detail an integrator needs.

• Authentication. Every route needs Authorization: Bearer zscim_…. There is no session and no other credential. The token is shown once when it is generated; only its SHA-256 hash is stored. At most 10 tokens can be active at a time. A missing, malformed, unknown or revoked token gets 401 with a SCIM error body and a WWW-Authenticate: Bearer header.
• Supported features. PATCH and filtering are supported; what a PATCH accepts is set out under SCIM PATCH: Operations, Paths And Errors, below. Bulk operations, sorting, ETags and password change are not, and the discovery document says so.
• Filters. Only <attribute> eq <value> clauses, joined by and. Users can be filtered on userName, externalId, emails.value and id; groups on displayName, externalId and id. Any other operator or attribute, or a filter longer than 1,000 characters, is 400 with scimType: invalidFilter.
• Paging. startIndex is 1-based. count defaults to 100 and is capped at 200 per page.
• Request bodies. application/scim+json or application/json, up to 1 MB. Malformed JSON is 400 invalidSyntax; a larger body is 413.
• User attributes read. userName, externalId, emails (the primary entry, else the work entry), name.givenName, name.familyName, title, active, phoneNumbers, and from the enterprise extension department, employeeNumber and manager. The sign-in email is taken from emails, or from userName when it is an email address; a create with neither is 400 invalidValue.
• Errors. Every error uses the SCIM error schema (urn:ietf:params:scim:api:messages:2.0:Error) with status, detail and, where it applies, scimType. A duplicate userName, externalId or group name is 409 uniqueness. The primary administrator is 403; so is a user owned by another directory connection. An unknown path is 404.
• Rate limit. 600 requests per minute per client IP at the gateway.
• Policy defaults. The provisioning policy (GET / PUT /api/v1/user-management/scim-provisioning/settings, manage_security) starts with onboardOnCreate: false and allowGroupCreate: true. With group creation off, POST /scim/v2/Groups is 403.

The token and policy routes (/api/v1/user-management/scim-provisioning/*) are listed in the API Reference.

SCIM PATCH: Operations, Paths And Errors

PATCH /scim/v2/Users/:id and PATCH /scim/v2/Groups/:id take the standard PatchOp message: a JSON object with schemas naming urn:ietf:params:scim:api:messages:2.0:PatchOp and a non-empty Operations array. A successful call answers 200 with the whole user or group as it now stands. On a user, the operations are applied in the order given. On a group they are combined into one change, as set out under Group Operations, below.

• Operations. op is add, replace or remove, in any letter case (Replace is accepted). The array may be sent as Operations or operations.
• Path form. An attribute name, optionally followed by a filter in square brackets, optionally followed by a dot and a sub-attribute: active, title, name.givenName, emails[type eq "work"].value. A path may start with a schema URN and a colon; the enterprise extension is addressed that way, as in urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department. The filter inside the brackets follows the same rule as a list filter: eq clauses joined by and.
• No path. An add or replace without a path takes an object as its value, and each key of the object is read as a path. A key may be dotted ("name.givenName") or carry the URN prefix, and the enterprise extension URN may be a key holding an object of its own.
• On a user, an add or replace with a path and no value is skipped, and the rest of the operations still apply. A group reads a missing value differently: see the table under Group Operations.
• Booleans. active is read from a JSON boolean, from the text "true" or "false" in any letter case ("False" is accepted), or from 1 or 0.
• User attributes a PATCH changes. The ones listed under User attributes read, above. A remove clears title, phoneNumbers, externalId and the enterprise department, employeeNumber and manager; a remove on active, userName, name.givenName or name.familyName leaves the stored value as it is. Setting active to false on an active account suspends it.

Group Operations

A group PATCH reads three paths only: members, displayName and externalId, in any letter case. A member is named by the user’s SCIM id.

• Order inside one request. The operations of one group request are not applied one after another. A rename and an external id are saved first, then a single membership change is worked out from all the operations together. If any operation is a replace of members, it decides the final list, whatever the same request adds or removes and wherever it sits in the array; with more than one, the last decides. A remove of members with no value removes everyone who was a member before the request, and users the same request adds who were not members before are still added.
• Privileged groups. Adding a member to a group that grants privileged access is 403 until an administrator allows that group under Security Settings → Provisioning (SCIM). The refusal is written to the audit log as SCIM_GROUP_PRIVILEGED_DENIED. No membership change from that request is written, but a rename or external id sent in the same request has already been saved.
• Groups created in Zonitix and opted in to SCIM take membership changes only: a rename sent for one is ignored and its external id is left as it is.
• A member id that is not a whole number, or that names no active user, is ignored and the rest of the change applies.
• Members owned by another SCIM connection are left out of the change, and SCIM_OWNERSHIP_REFUSED is written to the audit log.

PATCH Errors

These are in addition to the 401 for a bad token and the body errors listed under SCIM 2.0 Provisioning, above. A row marked none carries no scimType.