# Enterprise SSO

From [Descope Enterprise Identity](https://learn.descope.io/c/b2b) — Enterprise SSO, tenant-based identity, and the provisioning patterns that arrive with enterprise customers.

Take this course interactively at https://learn.descope.io/c/b2b/enterprise-sso

---

![Choosing SAML or OIDC. 3 minutes.](video:enterprise-sso-choosing-saml-or-oidc)

After five lessons on configuring, mapping and debugging both protocols, it is worth being direct about something that surprises people new to enterprise SSO: you rarely get to choose.

In the overwhelming majority of deployments the protocol is dictated by what the customer's IT department already has configured for that integration. If their Okta app is set up as SAML, you are doing SAML. Where you do get a say is your own product's documentation and default recommendation — the guidance you give a customer setting up their first connection who genuinely has not committed either way.

## When a customer offers both

- OIDC is lighter to configure and debug — a few endpoint URLs and a client secret, against SAML's XML metadata, certificates, and NameID quirks
- OIDC has no standardized groups claim, so group-based role mapping needs the IdP explicitly configured to emit one
- SAML is the more universal enterprise default and reliably sends groups in the assertion
- SAML carries a heavier configuration surface and the certificate rollover overhead from the previous lesson

If the customer does not care and their IdP handles both cleanly, OIDC is usually the lower-friction choice to support long-term. If group-based authorization is central and you cannot be sure their team will configure an OIDC groups claim correctly, SAML is the safer default.

## What each costs you in support load

- SAML — certificate lifecycle: rotation, expiry monitoring, and the manual rollover when a connection is not on a metadata URL
- OIDC — claim correctness: with no standard shape for a groups claim, every OIDC customer's authorization setup is slightly bespoke

Neither protocol is less work. They shift where the work shows up, and "why don't my roles show up" tickets skew toward OIDC tenants for exactly that reason. Knowing which failure mode you are trading for which is the useful thing to take away, not a universal recommendation.

## Key terms

- Protocol parity — that Descope supports both with equivalent mapping, JIT and SCIM capability, so the choice rarely limits what you can build.
- Groups claim — the OIDC token field carrying group membership, with no standard name or guaranteed presence.

## Summary

- That the customer's existing IdP configuration almost always decides the protocol
- What to recommend when they genuinely offer both, and why it depends on roles
- That neither is less work — they trade certificate lifecycle against claim correctness

---

![JIT Provisioning. 3 minutes.](video:enterprise-sso-jit-provisioning)

SSO answers who this user is. It does not answer whether they already exist in Descope — that is what provisioning is for, and JIT is the lightest-weight way to get it.

With JIT enabled on a tenant's SSO connection, Descope creates the user record on their first successful SSO login, from whatever attributes and groups the assertion supplied. On every login after that, it refreshes those same mapped attributes and group-derived roles from the latest assertion. So JIT is not only a signup mechanism: it is also how a profile and its access stay current for as long as somebody keeps signing in.

## Why teams reach for it first

- No directory sync to stand up before SSO can go live
- No users to pre-create, and no import to reconcile
- Toggled per SSO connection, alongside the connection's other settings
- A customer's own IT admin can turn it on from inside the Setup Suite

## Where JIT stops and SCIM starts

- JIT only ever hears about a user when that user shows up and logs in
- SCIM is a push channel — the IdP tells Descope about creates, updates and deactivations directly, with nobody signing in
- They are not exclusive: many tenants run SCIM for lifecycle and JIT purely for attribute refresh on login
- Once SCIM is a tenant's only writer, JIT can be turned off entirely

The distinction that matters is deprovisioning. JIT has no concept of somebody leaving the company, because leaving produces no login. That is the whole reason a tenant with a real offboarding requirement eventually wants SCIM, whatever JIT is doing for them today.

## Key terms

- JIT Provisioning — creating and updating a user from IdP-supplied attributes on each successful SSO login.
- SCIM — the directory-sync protocol letting an IdP push user and group changes to Descope directly.
- Default Roles — the roles Descope assigns when no group mapping matches the signed-in user.

## Summary

- That JIT creates a user on first login and refreshes attributes and roles on every login after
- That it has no concept of offboarding, and why that follows from how it is triggered
- That JIT and SCIM commonly run together, each doing the half it is good at

---

![SAML and OIDC Fundamentals. 5 minutes.](video:enterprise-sso-saml-and-oidc-fundamentals)

Every SSO connection in this module rests on the same handful of concepts. Get these solid now and the rest — configuration, setup, troubleshooting — is applying them.

Every SSO handshake has exactly two sides. The Identity Provider authenticates the user, and for your customers that is usually Okta, Microsoft Entra ID, Google Workspace, or a similar enterprise directory. The Service Provider is the application the user is trying to reach. Descope handles the federation on your behalf — validating signatures, parsing assertions, exchanging tokens — so you never implement any of it yourself.

## The four values every SAML login turns on

- The IdP's SSO URL, sometimes called the Login URL — where Descope sends the signed AuthnRequest
- The IdP's Entity ID — who Descope expects the response to have come from
- Descope's ACS URL — where the IdP posts the signed SAMLResponse back
- Descope's SP Entity ID — the audience the assertion has to name

Two of those live in the customer's identity provider and two are generated for the tenant and handed to the customer to paste in. The user clicks Sign in with SSO, Descope redirects them to the IdP, the IdP authenticates them however it likes, and it posts an assertion back. Descope validates the signature against the IdP's public certificate, checks the audience, and confirms the issuer. Get any one of the four wrong and the loop breaks somewhere predictable, which is exactly what the troubleshooting lesson walks through.

SAML and OIDC solve the same problem with different payloads. SAML carries a signed XML assertion. OIDC exchanges an authorization code for an ID token, a compact JWT verified against the IdP's published JWKs. Metadata is what makes either tractable: rather than copying six values by hand, most IdPs publish a single URL bundling the entity ID, endpoints, and signing certificate. Point the other side at that URL and it configures itself — and, critically, re-fetches when the IdP rotates its certificate. Manual entry works, but it does not pick up changes on its own.

## Key terms

- Identity Provider (IdP) — the system that authenticates the user: Okta, Entra ID, Google Workspace, or similar.
- Service Provider (SP) — the application the user is trying to reach. Descope acts as the SP toward the customer's IdP.
- ACS URL — Assertion Consumer Service URL, the endpoint where the IdP posts the signed SAML response.
- Entity ID — a unique identifier for one side of the exchange; both the IdP and the SP have their own.
- Metadata URL — one URL bundling entity ID, endpoints, and certificate, so configuration can refresh itself.
- Claims — the attributes an IdP sends about the user, mapped into Descope fields on login.

## Summary

- That Descope is the SP inside the exchange, and that Federated Apps is the opposite role
- The four values a SAML login turns on, and which side owns each
- Why a metadata URL survives certificate rotation and a manual entry does not
- That SAML carries signed XML and OIDC carries a signed JWT, for the same job

---

![SSO Setup Suite. 4 minutes.](video:enterprise-sso-sso-setup-suite)

Everything in the previous two lessons — SSO URLs, entity IDs, certificates, attribute and group mapping — can be configured by hand in the Console. In practice, almost nobody should do that by hand more than once. The SSO Setup Suite is Descope's guided interface for the same work, and it is the path this module's activity uses.

## What the guided flow covers

- IdP configuration for SAML or OIDC, from templates for Okta, Entra ID, Google Workspace and a dozen others, plus a generic path for anything else
- User attribute and group mapping
- A live connection test, including the actual assertion or token that came back
- SCIM provisioning setup
- Cross-App Access configuration, for customers whose agents need to reach your product

The suite is built for two different people to use the same flow. Customer self-service is the common case: generate a link scoped to one tenant, send it to the customer's IT admin, and they configure their own IdP without touching your Console or waiting on you. Configuring on a customer's behalf is the same link, opened by you — usually faster and less error-prone than hand-editing the tenant's SSO form while reading values off a screen share.

A generated link carries a temporary token scoped to Tenant Admin permissions for that one tenant, and expires on a schedule you control. A `target` query parameter can point it straight at a named IdP template, so an admin lands on "Configure Okta" rather than browsing a gallery.

> [!NOTE]
> This lesson is an introduction rather than a walkthrough. The next module covers self-service setup in depth — generating and delivering links, what the tenant admin actually sees, and how to embed or revoke that access.

## Key terms

- SSO Setup Suite — Descope's guided interface for configuring a tenant's connection, mapping, and SCIM.
- Setup Suite link — a generated, temporary, Tenant-Admin-scoped link that opens the suite for one tenant.
- Connection test — the step that runs a real login against the configured IdP and shows what came back.

## Summary

- That the suite replaces per-field configuration with one guided flow
- That the same link serves customer self-service and configuring on their behalf
- That a target parameter skips the gallery and opens a named IdP directly
- That the connection test proves a login works, not merely that a record exists

---

![SSO Troubleshooting. 5 minutes.](video:enterprise-sso-sso-troubleshooting)

Every failure below only makes sense next to the redirect loop and the mapping rules from the first two lessons. You are about to meet those same four values again, this time as the thing that broke.

## Redirect mismatch

- Symptom — login fails immediately after the user authenticates, often before Descope validates anything, complaining the redirect URL is not approved
- Cause — the redirect URL your app requested is not in the SSO application's approved list, usually a copy-paste mismatch or a URL that changed on one side only
- Fix — add the exact URL to the approved list; for IdP-initiated login, confirm a Post Authentication Redirect URL is set at project or tenant level
- Codes — `E061016` for an unapproved redirect URL, `E061206` for IdP-initiated login with no Post Authentication Redirect URL configured

## Certificate expiry and rollover

- Symptom — logins that worked start failing with a signature or assertion-handling error, with no change on your side
- Cause — the IdP rotated its signing certificate and Descope still holds the old one
- Fix, metadata URL — re-save or re-fetch the connection so Descope reloads current metadata. This is the entire reason metadata URLs exist
- Fix, static upload — add the new certificate to the additional certificates list, wait for the IdP's cutover, drop the old one, then test
- Codes — `E062604` for a SAML private key that will not parse, `E062606` for an x509 certificate that will not

Static uploads are the only path that can emit a `SAMLCertificateExpiry` audit warning ahead of the expiry, at the cost of needing this manual step every time the IdP rotates.

## Missing attributes

- Symptom — the user authenticates successfully but profile fields are empty, or a mandatory attribute check fails during testing
- Cause — almost always a naming mismatch rather than a missing IdP feature. Names are case-sensitive, and Entra in particular sends full URI-format claim names rather than short ones like `email`
- Fix — read the raw assertion rather than guessing. The Setup Suite's connection test shows exactly what came back; SAML Tracer does the same for a manual configuration

## Domain resolution

- Symptom — a generic "tenant not found" or "SSO not configured for this account" error, before the user ever reaches the IdP
- Cause — the email domain does not match any configured SSO Domain, often because it was set on the wrong configuration in a multi-IdP tenant
- Fix — confirm the domain is on the specific configuration the user should hit, not merely somewhere on the tenant. If several tenants legitimately share a domain, enable Allow Duplicate SSO Domains Across Tenants and give the user a picker rather than guessing

## Role mapping

- Symptom — login succeeds, JIT creates the user, and they arrive with no roles or the wrong ones
- Cause — the Groups attribute name does not match the IdP's claim name, or the IdP sent group display names where the mapping expects object IDs, or the IdP never sent groups at all
- Fix — confirm groups are present in the raw assertion before touching the mapping. The connection test flags this directly with `E062028` when Groups is mandatory and none arrived

OIDC deserves a note here: it has no standardized groups claim the way SAML does, so an OIDC tenant only sends groups if somebody explicitly configured it to.

## IdP-side assignment

- Symptom — one specific user, often a new hire, simply cannot be found; either the IdP rejects them before Descope is reached, or Descope reports them unknown
- Cause — provisioning is entirely IdP-driven. A user reaches Descope only if they are assigned to the application on the IdP side, directly or through a group
- Fix — check Audits for a `SCIMEvent` matching the user. If there is none, the IdP never pushed them, and the fix is entirely IdP-side

Group-to-role mapping has no bearing on this at all. It decides what a user can do once provisioned, never whether they get provisioned. Confirm SSO and SCIM point at the same IdP application, too — split configurations are a frequent source of "login works, but Descope says user not found."

## Key terms

- Redirect mismatch — a failure caused by the app's redirect URL not appearing in the approved list.
- Certificate rollover — updating Descope with a newly rotated signing certificate without breaking login.
- SAML Tracer — a browser extension for capturing the raw SAML request and response during a login.
- IdP-side assignment — the requirement that a user be assigned to the application in the IdP before it will authenticate them.

## Summary

- That nearly every failure traces to one of the four redirect-loop values, a stale certificate, or a mismatched name
- That a metadata URL connection self-heals on rotation and a static upload does not
- That missing roles is almost never a mapping bug — check whether groups arrived at all
- That a user Descope cannot find is an IdP assignment problem, which no mapping change will fix

---

![Tenant-Based SSO Configuration. 5 minutes.](video:enterprise-sso-tenant-based-sso-configuration)

SSO in Descope is configured per tenant, never at the project level. Every customer organization you onboard as a tenant gets its own SAML or OIDC connection, under that tenant's Authentication Methods.

Most tenants need exactly one IdP connection, and that is the default Descope creates. Some genuinely need more — a corporate Okta directory plus a contractor Entra directory under the same organization, or regional IdPs under one parent. Descope supports that with additional SSO configurations on the same tenant, each with its own `ssoId`. This is a different thing from ordinary multi-tenant SSO, where each customer simply gets their own tenant with one IdP; reach for additional configurations only when one tenant genuinely needs to route different users to different providers.

## What an additional configuration carries

- Its own SAML or OIDC settings, independent of the tenant's other connections
- Its own attribute and group mapping
- Its own SCIM pipeline, if you use one
- Its own Setup Suite link, so a tenant admin configures exactly the connection you intend

After login, `lastAuth.ssoId` records which configuration authenticated the user, so a flow can branch on it.

Because SSO is per tenant, Descope has to work out which tenant — and which configuration inside it — a user belongs to before it can redirect them anywhere. That step is often called home realm discovery.

## Three ways to route a user

- SSO Domains — assign email domains to a tenant or to a specific configuration, and a matching address routes automatically
- An explicit `ssoId` — for shared domains, a picker in your own UI, or a deep link straight to one provider
- Tenant slug or ID — when several domains sit under one tenant, or you would rather decide in your own app logic than infer it from an email address

> [!NOTE]
> If a tenant has SSO enforced but no SSO Domain configured, Descope cannot route users to that connection and login can never succeed for them. Marking SSO Domains as a mandatory attribute in project-level SSO settings prevents this misconfiguration from shipping.

Once a connection routes a user correctly, mapping decides what Descope does with the claims the IdP sent. User attribute mapping turns IdP fields into Descope user fields or custom attributes. Group mapping turns IdP group membership into Descope roles on that tenant — an Engineering group resolving to a Developer role — and, if you use Fine-Grained Authorization, the same group can additionally resolve to FGA relations. Both apply identically across SAML and OIDC, so switching a tenant's protocol later does not lose the mapping. Default roles cover the case where no group mapping matches, which matters most for tenants relying on JIT.

## Key terms

- Tenant SSO configuration — the SAML or OIDC connection configured for one tenant.
- ssoId — the identifier for one SSO configuration on a tenant, used when a tenant has more than one connection.
- SSO Domain — an email domain assigned to a tenant or configuration, used to route users to the right IdP.
- Home realm discovery — working out which tenant, and which IdP within it, a signing-in user belongs to.
- Group mapping — the rules turning IdP group membership into Descope roles, and optionally FGA relations, on login.

## Summary

- That SSO is configured per tenant, never project-wide
- When one tenant legitimately needs more than one connection, and when it does not
- The three routing options, and which case each one covers
- That attribute and group mapping survive a tenant switching protocol

---