# Self-Service SSO Setup 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/self-service-sso --- ![Embedding and Revoking. 3 minutes.](video:self-service-sso-embedding-and-revoking) Instead of sending a customer's IT admin to a Descope-hosted page, you can embed the whole Setup Suite inside your own product with an iframe. No token belongs in that URL: the embedded suite relies on the authentication context already present in your app, so a valid Descope JWT with Tenant Admin permissions needs to be available in the browser session. ## Parameters worth knowing - `tenantId` — pins a specific tenant, for a user who belongs to more than one - `ssoId` — pins a specific SSO configuration, when a tenant has several - `theme` — light, dark, or the default `os`, which follows the visitor's system preference If you would rather not embed anything, an already-authenticated tenant admin can visit the suite directly at a hosted URL, with no temporary token in the address bar. Descope checks their Tenant Admin permissions from their existing refresh token before the page loads. That route is for admins who already sign in to your product; the generated link is for admins who do not have an account with you yet and need a self-contained way in. A generated link stays valid until its stated expiration, but you do not have to wait it out. ## Three places to revoke one - The Revoke Link button on the tenant's configuration page in the Console - The Management API - The Management SDK's `RevokeSSOConfigurationLink` call Revoking is worth doing the moment setup is finished, rather than leaving a live link sitting in an old email thread — and it is the fix when a link goes to the wrong inbox and needs regenerating. ## Key terms - Embedded setup — loading the suite inside your own admin UI, relying on the signed-in user's session instead of a temporary token. - Hosted route — the direct, tokenless URL an already-authenticated tenant admin can visit on their own. - Revoke — invalidating a generated link before its expiration, from the Console, the API, or the SDK. ## Summary - That embedding removes the token from the URL and depends on your app's own session instead - Which route suits an admin who already has an account, and which suits one who does not - That a link lives until it expires or you revoke it, and where the three revoke paths are --- ![Generating and Sending an Admin Link. 4 minutes.](video:self-service-sso-generating-and-sending-a-link) ## Three ways to generate the same link - The Console — a Generate Link button on the tenant's configuration page, which you can copy or email directly. Right for a one-off, or when you are configuring on the customer's behalf - The Management API and SDKs — `generateSSOConfigurationLink(tenantId, expireDuration)` and its REST equivalent, for triggering generation from your own backend - A Flows action — Generate SSO setup suite admin link, for making link generation part of an automated onboarding sequence with no manual step Which one fits depends on how automated onboarding needs to be, not on what the link can do. All three produce the same thing. Inside a flow, the action stores its result under the dynamic key `{{adminLinks.ssoConfiguration}}`. From there you can put that key into a link on a flow screen, or hand it to an email or SMS connector to send directly to the tenant admin, with no separate delivery step. A typical onboarding flow checks whether the signed-in user is new to the tenant, grants them the Tenant Admin permission, generates the link and emails it — all before the user has finished their first session. > [!WARNING] > `{{adminLinks.ssoConfiguration}}` only holds a value after the action that generates it has already run earlier in the same flow. A screen or connector reading it before that point finds nothing, which is the same flow-context ordering rule that catches people with connector responses. Whichever method you use, the link carries a temporary token scoped to that tenant — and, when the tenant has more than one SSO configuration, to a specific `ssoId`. An optional `target` query parameter sends the admin straight to a named provider's setup screen instead of the full gallery. ## Key terms - Generate SSO setup suite admin link — the Flows action creating a link as part of an onboarding or provisioning flow. - `{{adminLinks.ssoConfiguration}}` — the dynamic key holding the generated link, once that action has run. - generateSSOConfigurationLink — the Management SDK method, and matching API endpoint, that generates the same link outside Flows. ## Summary - That the same link comes from the Console, the Management API, or a Flows action - Which of the three fits an automated onboarding path, and why - That the dynamic key is empty until the action that fills it has run - That a target parameter can skip the provider gallery entirely --- ![What the Tenant Admin Sees. 4 minutes.](video:self-service-sso-what-the-tenant-admin-sees) Once the tenant admin opens the link, they pick their identity provider from a gallery of named templates — Okta, Entra ID, Google Workspace and others — or fall back to a generic SAML or OIDC path if theirs is not listed. ## What the suite walks them through - Service Provider Information — the tenant-specific values they paste into their own IdP - Identity Provider Information — a metadata URL, or the SSO URL, Entity ID and certificate if they are configuring by hand - Attribute mapping — matching fields in the assertion, such as email or a custom attribute, to attributes that already exist in your project - Group mapping — matching the IdP's groups to Descope roles, or to FGA relations The mapping step has a consequence worth designing for. The admin can only map to attributes and roles the Tenant Admin role is permitted to see, so keeping something off their list is a matter of excluding it from that role's permissions rather than hiding it in an interface. Before anything goes live, the admin runs a connection test. It redirects them to their real identity provider, authenticates, and returns with the resulting user profile and roles shown next to the raw assertion in an assertion viewer. That is a full round trip through the actual IdP, not a form check, which is why it catches mismatched attribute names and missing group claims that a validator never would. > [!NOTE] > If your project marks Groups as mandatory and the response does not include one, the test fails with `E062028`. That almost always means the test user is not assigned to a group at the IdP, or the claim name Descope is reading does not match what the IdP actually sends. SCIM setup, for tenants that need directory sync, reuses the attribute and group mapping already configured for SSO. The admin's remaining work is generating an access key and copying the provisioning base URL into their IdP. ## Key terms - Attribute mapping — matching fields in the IdP's assertion to attributes that already exist in your Descope project. - Group mapping — matching the IdP's groups to Descope roles, or to FGA relations, so access follows group membership. - Assertion viewer — the part of the connection test showing the raw response next to the resulting profile and roles. ## Summary - What the admin configures, in the order the suite asks for it - That their mapping options come from the Tenant Admin role's permissions, not from a UI setting - That the connection test is a real round trip, which is why it catches what a validator cannot - That SCIM reuses the SSO mapping rather than asking for it twice --- ![Why Self-Service SSO Matters. 3 minutes.](video:self-service-sso-why-self-service-matters) Every other lesson in this course treats SSO configuration as something you do: sitting across from a customer's IT admin, walking them through certificate fields and metadata URLs on a shared screen. This module is about the version where you are not in the room at all. ## What configuring SSO by hand actually costs - Scheduling time with the customer's IT admin, on both calendars - Walking them through provider selection, then copying metadata URLs and certificates back and forth - Mapping user attributes and groups by hand while they watch - Testing the connection together before anyone is confident it works That is an hour of your time and an hour of theirs, and it does not scale past your first few enterprise customers. Every additional tenant is another meeting on somebody's calendar. A generated admin link turns that meeting into an email. You send the customer's IT admin a link, and they work through provider selection, attribute mapping and testing on their own schedule, without needing an account in your product or a slot on your calendar. In an enterprise deal, being able to say "your team can set this up themselves in fifteen minutes" is a materially different pitch from "let's schedule an onboarding call." ## Key terms - SSO Setup Suite — Descope's guided, self-service portal where a tenant admin configures their own SAML or OIDC connection and SCIM. - Tenant Admin — the role carrying the permissions a customer's IT admin needs to configure SSO for their own tenant. - Admin link — a generated URL carrying a temporary, tenant-scoped token, giving Setup Suite access without creating a standing account. ## Summary - That manual configuration means a screen share, and a generated link means it happens without you - That this is a difference in the sales conversation, not only in the Console - That the hours spent walking admins through SAML fields are the ones that do not scale ---