SSO Login Flows
An SSO login can start in two places: on your app (SP-initiated) or at the customer's identity provider (IdP-initiated). Most B2B apps need both. The diagram below compares them.
The most common flow, and likely the first one you'll test. The user starts on your sign-in page, enters their email, gets redirected to their identity provider to authenticate, and is redirected back to your app.
This is what the Getting Started with SSO guide sets up.
SP-Initiated
The user starts on your sign-in page, gets redirected to their IdP, authenticates, and comes back to your app. This is the flow you'll test first, and what Getting Started with SSO sets up.
IdP-Initiated
The user starts in their IdP (Okta app tile, Entra My Apps, and so on), picks your app, and lands in your product already authenticated. Developers often ship SP-initiated only and discover IdP-initiated the hard way when a customer IT admin "just clicks the tile."
When Descope receives an IdP-initiated SAML assertion, it validates it and then runs an internal SP-initiated code exchange, so your callback / SDK exchange path stays the same as normal SSO.
Note
You can't sign a user out of Descope using Single Logout (SLO) from a tenant's SSO provider. See SAML Security for how to handle logout.
What You Must Configure
IdP-initiated needs a Post Authentication Redirect URL, the page Descope sends the user to after it finishes the internal exchange. Without it, login fails with E061206 (missing redirect URL for IdP-initiated login).
Set it at:
- Project level: SSO Auth Method settings, which supports dynamic URLs if you use different domains per tenant
- Tenant level: the tenant's SSO configuration (or the SSO Setup Suite)
That URL should be an HTTPS page in production that either runs a Descope Flow or exchanges the code with your SDK.
With Flows
- Add a condition that detects IdP-initiated. If true, complete login automatically. If false, show your normal sign-in screen for SP-initiated SSO.
- Point the Post Authentication Redirect URL at a page that hosts that flow.
With SDKs
Point the Post Authentication Redirect URL at a page that reads the code query parameter, then exchange it the same way as SP-initiated SSO:
Test Both Paths
- SP-initiated: sign in from your app with a test user.
- IdP-initiated: from the IdP's app portal, launch your app (the customer assigns the app in Okta / Entra / etc.).
- Confirm both land authenticated with the right tenant and roles (SSO mapping).
- Check Audits for
LoginSucceeded(and failures if something's off).
Troubleshooting IdP-Initiated
| Symptom | Likely cause |
|---|---|
E061206 | Post Authentication Redirect URL not set for the project or tenant |
| User lands on wrong page / blank | Redirect URL doesn't host your flow or code-exchange page |
| Works from your app, fails from IdP tile | IdP-initiated never configured; only SP-initiated was tested |
| Assertion / cert errors | IdP cert or metadata out of date; certificate rotation |
More codes: SSO troubleshooting.
Related
- Getting Started with SSO
- SSO Setup Suite
- SAML Security
- SSO tutorials (IdP-initiated video)
SSO User and Group Mapping
Map IdP attributes and groups to Descope users, RBAC roles, and FGA relations for SAML and OIDC SSO.
Risks in Merging SSO and Non-SSO Identities
Learn about the risks of merging SSO users with non-SSO identities, including security implications and best practices for identity management.