This page walks through the SSO login flow end to end — the redirect, the response validation, how the user is matched, and exactly what appears when a step fails.
Overview
On load, the login page reads the tenant's active sign-in methods — scoped to the app, so an app's own methods take precedence over the workspace default — and shows one of three surfaces: SSO buttons (a "Continue with …" button per active SAML or OpenID method), a Username + Password form (for Email ID and Password, and for LDAP), or a Username-only form (for an OTP method, followed by a one-time code). When more than one exists, they're prioritized SSO, then password, then OTP, and a "Login via Username" link switches from the SSO buttons to the credential form. Password-family methods — Email/Password, OTP, LDAP — never redirect; they use that shared on-page form. The identifier field is always Username regardless of method, so switching to OTP doesn't change it to a phone field.
What Happens When a User Clicks an SSO Button
Redirect out. The platform records a one-time login state — which provider, where to return to, which domain the login started on — and sends the browser to the IdP: for SAML via HTTP-Redirect or HTTP-POST per the configured binding, with the login state carried as the RelayState; for OpenID via the Authorisation URL with a state parameter. Any configured Additional Authorization Parameters, plus a login_hint if the login page supplied one, ride along.
The user authenticates at the IdP. With SAML's force-reauthentication option enabled, the IdP is asked to re-prompt for credentials even if the user already has an IdP session.
Callback. The IdP posts back to the platform's completion endpoint. The platform validates the response, resolves the user, optionally runs MFA, then creates the session and redirects the browser to the original destination.
Single-use. Each login attempt is single-use — replaying the same callback link fails with "This login request has already been used. Please initiate a new login." If the callback lands on a different domain than the login started on, the browser is first bounced back to the original domain so cookies are set correctly.
What Is Validated on a SAML Response
Checks run in this order:
Response present — a callback without a SAML response fails: "SAML response is missing. Please try logging in again."
Correlation — for platform-initiated logins, the response's InResponseTo must match the original request id: "SAML response validation failed. The response does not correspond to the original login request." IdP-initiated logins using the Default RelayState skip this check by design.
Signature — required and verified whenever an X.509 certificate is configured: "SAML response signature validation failed. Please verify the SSO configuration." This is skipped only if no certificate was configured.
Assertion present — "SAML response does not contain valid assertions."
Validity window — NotBefore/NotOnOrAfter is enforced strictly, with zero clock-skew tolerance: "SAML assertion is not yet valid. Please try logging in again." or "SAML assertion has expired. Please try logging in again." If users hit these intermittently, check the IdP's clock and assertion lifetime.
Replay — the assertion id is remembered until the assertion's own expiry (or about 60 minutes if the IdP set none); a second use fails: "This SAML response has already been used. Please initiate a new login." Assertions lacking an id skip replay protection rather than being rejected.
Username extraction — from the configured Username Attribute Statement, else the subject NameID: "Username attribute not found in SAML response. Please verify the SSO attribute mapping."
What Is Validated on an OpenID Login
The platform exchanges the returned code for tokens at the Access Token Endpoint, authenticating with the Client ID and Secret per the configured authentication type, then calls the User Info Request URL with the access token. Failures and their messages: "Failed to obtain access token from identity provider" (bad code exchange, wrong client secret, wrong token endpoint), "Failed to retrieve user details from identity provider." (the user-info call returned nothing), and — when the Username JSON Path finds nothing in the user-info response — "OpenId login failure please very provider config." ID-token and access-token claims are decoded for attribute mapping and session attributes; profile data is taken from the user-info response you configured.
How the User Account Is Resolved
Resolution is by username, exactly:
Match found — that account is used. Email is not used for matching, so if the IdP sends a different username than the existing local account's, a second account can be created (or the login can fail with JIT off) even though the email matches.
No match, JIT Provisioning on — the JIT User Criteria, if any, are evaluated against the incoming profile; on pass, the account is created with name, email, phone, and mapped custom attributes from the IdP and flagged as an SSO user. On fail: "User criteria check failed".
No match, JIT off — the login fails; users must be pre-created. For SAML this surfaces as the generic SSO error.
Then, for the resolved account, checks run in order:
State check — non-active accounts are refused: "User is disabled", "User is deleted", "User is dormant", or "User is temporarily locked".
Login Restriction — the Login User Criteria are evaluated on every login, existing users included: "User criteria check failed".
Attribute refresh — with JIT Provisioning on, mapped attributes are rewritten from this login's data; teams, roles, state, locale, and unmapped custom attributes are preserved.
MFA — if the method has an MFA config, the user is redirected to the verification page before any session exists.
What Session a Successful SSO Login Creates
A platform session is created, tied to the identity provider: its lifetime is the method's Session Expiry Time (in minutes; the platform default — typically 1 day — applies if unset), delivered as a secure, HttpOnly cookie. If the method enables refresh tokens, a refresh cookie is also set and the session renews silently until the refresh expiry (in days). Restrict Multiple Sessions deletes the user's other sessions at this moment and pushes a live logout to any open tabs. Single Tab Session sets its marker cookie. The login is recorded — login activity and audit trail, with IP address — and a USER_LOGIN platform event is emitted; the session also stores any session attributes you mapped from the assertion or token for use inside apps. After the session is created, an optional post-login workflow configured on the provider can run (for example, to set headers or redirect somewhere specific); a post-logout workflow can likewise run at sign-out.
Where the User Lands When SSO Fails
If the app passed a failure return URL when starting the login, the browser is redirected there with the error message attached, shown by that page.
Otherwise, browser-based SAML/OIDC failures land back on the login page with the message displayed — for example "SSO login failed", or the specific validation message.
Unexpected errors — misconfiguration, an IdP outage, an unknown user with JIT off on SAML — show the generic "An error occurred during SSO login. Please verify the SSO configuration or try again later."; if the login state itself can't be found, "SSO login failed due to login state not found. Please verify SSO configuration."
Every failed login is captured in the user's activity and audit trail and emits a USER_LOGIN_FAILED platform event, with reason, provider, and IP, that you can subscribe to for alerting.
Common "Why Can't This Person Sign In With SSO?" Causes
Account not created and JIT off — pre-create the user or enable JIT Provisioning.
Username mismatch — the IdP's username mapping doesn't produce the exact username of the existing account; matching is never by email.
Account disabled, deleted, dormant, or locked — fix the user's State on the Users screen.
Login Restriction criteria — the user's attributes no longer match the Login User Criteria; these are re-checked every login, and attribute sync may have just updated the very attributes being checked.
Clock drift or short assertion lifetime — "not yet valid" or "has expired" messages, with no clock-skew grace.
Replayed or stale login link — users bookmarking the IdP callback or using the browser Back button hit the single-use protections; they should start again from the login page.
Missing certificate vs. signature errors — if the IdP rotated its signing certificate, re-import metadata or paste the new certificate.
Method toggled off — its button is gone from the login page.
Notes
Most SSO support tickets trace back to a handful of predictable causes — watch for these proactively rather than diagnosing them one at a time:
Watch for USER_LOGIN_FAILED events and alert on spikes rather than waiting for a support ticket.
Keep your IdP's clock synced — there is no clock-skew tolerance on SAML assertion validity.
Re-import IdP metadata or paste the new certificate promptly after any signing-certificate rotation.
Tell users not to bookmark an IdP callback link or use the browser Back button mid-login — both trip the single-use replay protection.
Confirm the Username Attribute Statement (SAML) or Username JSON Path (OpenID) produces exactly the username your existing accounts use, since matching is never done by email.
Re-check Login Restriction criteria whenever attribute sync changes the fields those criteria depend on — they're evaluated on every login.