SSO (Single Sign-On)
Note
If you're using a FedRAMP deployment of Descope, you must ensure your SSO provider is certified for FedRAMP High.
Descope supports SAML 2.0 and OAuth 2.0 / OIDC for Single Sign-On (SSO), so you can connect to any identity provider (IdP) that speaks either protocol. To use SSO you need to:
- Configure your project's SSO Settings under Authentication Methods → SSO in the Descope Console
- Configure an SSO connection for at least one tenant
Note
SSO is configured per tenant, not at the project level.
You need at least one tenant with SSO set up before users can sign in with SSO.
Built for B2B SSO
Descope is a fully multi-tenant based authentication platform. You can onboard each customer as a tenant with one or multiple SSO connections, then hand their admins self-service configuration through the SSO Setup Suite and Admin Portal.
Every tenant can also have its own SCIM provisioning, roles, and Flow styling.
One integration into Descope, and each customer is its own tenant with its own IdP. Their IT admins can configure SSO themselves through the SSO Setup Suite.
Choose Your Integration Approach
Two common ways to use Descope for SSO:
- Descope runs authentication: Use Descope Flows for login and sessions. SSO will be one of the actions in the flow.
- You keep your own sessions: Use Descope only for SSO via the backend SDK. At login, your backend validates a Descope token, then signs the user in the way it already does. You still get Admin Portal, SSO Setup Suite, RBAC, and tenant-level settings. (Client / mobile SDK guides exist for SPAs and native apps that must run the handshake on-device.)
If you're adding SSO beside an existing auth stack, start with Getting Started with SSO.
If Descope is your full auth layer, use the main Getting Started guide instead.
IdP and SP
Note
When we talk about SSO, we usually mean letting your customers sign into your app with their IdP.
If you want Descope to be an IdP for other applications, see Federated Apps instead.
You'll see these two terms everywhere in SSO docs:
- Identity Provider (IdP): the system that authenticates the user. For your customers that's usually Okta, Microsoft Entra ID, Google Workspace, or similar.
- Service Provider (SP): the application the user is trying to open. That's your product.
Your app is the SP. Descope acts as the SP toward the IdP, so you don't have to implement SAML or OIDC federation yourself.
Your app is the Service Provider. Descope acts as the SP toward the identity provider and handles the SAML or OIDC federation, so you don't build it yourself.
Tenant Identification Methods
Because SSO is configured per tenant, Descope has to know which tenant a user belongs to before it can send them to the right IdP. That step is often called home realm discovery.
You can identify the tenant in a few ways:
Note
A single tenant can also use multiple SSO providers, so different groups in the same org can log in through different IdPs.
For more information on how to configure different SSO providers within one tenant, see our guide on multiple SSO providers.
Option 1: SSO Domains
Note
This is different than the tenant-level email domain which is only really used for tenant's that don't use SSO.
Configure SSO domains for a tenant in the SSO Setup Suite, or manually under Authentication Methods → SSO when you select a tenant on the Tenants page.
Add the email domains that should use this tenant's IdP. Users with those domains are routed to that SAML/OIDC connection.
With the backend SDK, pass the user's email into sso.start (for example sso.start('alex@acme.com', redirectUrl)). Descope looks up the matching SSO Domain and returns the authorization URL for that tenant's IdP, so you don't have to resolve the tenant ID yourself.
See Getting Started and Backend SDK start options.
| Tenant Name | SSO Domain | User's Accessibility |
|---|---|---|
| SSO Tenant 1 | company-a.com | Users signing in from @company-a.com authenticate with SSO Tenant 1's IdP |
| SSO Tenant 2 | company-x.com, company-y.com | Users from @company-x.com or @company-y.com authenticate with SSO Tenant 2's IdP |
Option 2: Tenant Slug or ID
For more on flow input parameters, see Auth Helpers.
If one tenant spans multiple domains, or domain association doesn't fit your IdP, pass a tenant slug or ID into the flow instead. That routes the user to the right tenant regardless of email domain.
Use a slug or ID when:
- Several domains sit under one tenant
- Your IdP doesn't support domain-based routing
- You want to decide the tenant in your app, not from the email address
Configuring SSO for a Tenant
Each tenant gets its own SAML or OIDC connection.
Prefer the SSO Setup Suite: generate a link and either send it to the customer's IT admin or open it yourself when you're configuring SSO on their behalf.
The suite works with effectively any SAML or OIDC IdP (templates for common providers, plus generic config), and covers attribute/group mapping, a connection test, and SCIM.
If the Setup Suite isn't on your plan, configure the tenant manually with the SSO with SAML or SSO with OIDC guide.
Migrating from another auth provider or a homegrown SSO stack? You can often keep the customer's IdP settings as-is. See the SSO migration guide.
Where to Go Next
| Goal | Doc |
|---|---|
| First working SSO login | Getting Started with SSO |
| Customer self-service setup (any IdP) | SSO Setup Suite |
| Project SSO + Setup Suite + Admin Portal as code | Terraform → SSO Settings and Admin Portal |
| Multiple IdPs on one tenant | Multiple SSO providers |
| Create users on first login | JIT provisioning |
| Map groups and attributes (RBAC + FGA) | SSO mapping |
| SP- vs IdP-initiated | SSO login flows |
| Directory sync | SCIM |
| Cert / metadata rotation | Certificate and metadata rotation |
| Go-live / errors | Launch checklist, SSO troubleshooting |