# Enterprise Capstone 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/capstone --- Everything in this course has been one piece of an enterprise onboarding. This is the whole thing, once, for a single customer — and the point is less each individual step than what happens between them, because that is where real onboardings go wrong. ## The scenario - One enterprise customer, arriving with an identity provider they already use and expect you to accommodate - Their employees should sign in with their work accounts and never create a password with you - Their administrator should be able to run the setup themselves, rather than exchanging metadata files with you over email - Somebody at that company needs more access than their colleagues Use a real identity provider you can administer — Okta, Entra ID, Google Workspace, or a free developer tenant of any of them. A mock SAML endpoint will get you through configuration and will not teach you anything about the part that actually bites, which is what the IdP sends and what it does not. ## What to build - A tenant for that customer, with their email domain associated to it - An SSO connection on that tenant, SAML or OIDC, chosen deliberately rather than by whichever you met first - Domain routing, so a user typing their work address reaches that connection without choosing anything - Attribute and group mapping, so the identity provider's groups arrive as roles inside the tenant - JIT or SCIM provisioning, picked with a reason you can state - A self-service setup link, sent to the administrator, so the configuration is theirs to complete The provisioning choice is the one worth slowing down for. JIT creates a user the first time they sign in, which is simple and means a departing employee's record lingers until someone removes it. SCIM keeps the directory in step in both directions, costs more to set up, and is usually what an enterprise security review asks about. Either is defensible; arriving at one without noticing there was a decision is not. ## What "finished" looks like - A user at the customer's domain types their work address and is sent to their identity provider without picking anything from a list - They return authenticated, and a user record exists that nobody created by hand - Their token carries roles nested under that tenant's ID in the `tenants` claim, not at the root - A second user from the same domain who belongs to a different IdP group arrives with different roles - Your application refuses an action that user's roles do not permit, and the refusal happens in your code rather than in Descope - The administrator completed at least one part of the setup themselves, through a link rather than through you That third criterion is the one people skip and the one that matters. A role at the root of the token is a project-level role — it applies everywhere, including inside every other customer's tenant. If the role you mapped appears there rather than under the tenant ID, the mapping is wrong in a way that only shows up when you have a second customer, which is the worst possible time to find it. > [!WARNING] > Test with a user who belongs to no mapped group at all. A connection that works for everyone you tried it with, because everyone you tried it with happened to be in the admin group, is the most common way this configuration ships broken. > > What that user should arrive holding depends on a choice you may have made already: nothing, or exactly the Default Roles if you configured any — those are what Descope assigns when no group mapping matches. Either is correct. What matters is that you know which one you expect before you look, and that your application handles it rather than erroring. ## The failures worth meeting deliberately - An assertion arrives and is rejected — almost always the ACS URL or the entity ID differing between the two sides by a trailing slash - A user signs in and has no roles, because group mapping was never configured - A user never reaches their identity provider at all, getting "tenant not found" instead — the domain is somewhere on the tenant but not on the configuration they should hit - A user lands in a different customer's tenant, which takes Allow Duplicate SSO Domains Across Tenants plus nothing asking them which one they meant - SCIM changes do not appear, because the identity provider pushes on its own schedule rather than yours - Everything works for you and fails for the customer, because you tested as a tenant admin ## Where each piece was taught - The tenant, and why identity sits above it rather than inside it — Tenants - SAML versus OIDC, metadata, and what each side needs from the other — Enterprise SSO - Domain routing and JIT provisioning — Enterprise SSO - Handing the setup to the customer's own administrator — Self-Service SSO - Roles nested per tenant, and reading the multi-tenant token — Authorization at Tenant Scope - What your application still has to enforce on its own — Authorization at Tenant Scope ## Summary - That an enterprise onboarding is every module in this course happening at once, and that the seams between them are where it breaks - That SSO brings authentication and not authorization, so a working connection can still leave a user holding nothing - Why a role at the root of the token rather than under the tenant ID is a bug you will not notice until your second customer - That the provisioning choice between JIT and SCIM has consequences worth stating out loud - Which failures to go and cause on purpose, rather than meeting them during a customer's first week ---