Customizing SSO (Single Sign-On)
Descope implements SSO using the SAML 2.0 specification or OAuth 2.0 specification and supports any IdP that adheres to either. Before configuring within your tenants, you need to enable it by going to the SSO Auth Method, selecting Service Provider, and toggling it on.
SSO is configured for each tenant independently from each other upon clicking on the applicable tenant and selecting the SSO Configuration tab from the Tenants page.Note: SSO is only implemented for tenants and not at a project level. Add at least one tenant to the project to implement an SSO authentication flow.SSO Acronyms
To clarify terminology used in the documentation and the Descope console, these are some SSO acronyms that are important to know:
- Identity Provider (IdP) - the entity that authenticates users and passes on authentication and authorization attributes to the service provider. The IdP stores and maintains the database of end-user credentials, which you are using to authenticate your end user.
- Service Provider (SP) - the owner of the website, application, or service that grants access application or entity the user wants to access. The service provider receives trusted authentication and authorization attributes from the identity provider before granting the user access to a website, application, or service.
You are the SP providing your customers SSO access to your website, application, or service. Descope will act on your behalf as the SP, so you don't have to wade through the complexities of implementing SSO.
Using OIDC or SAML
No matter which authentication specification your IdP uses, you'll need to configure your SSO domains.
TheSSO Domains field under Tenants -> Select Tenant -> Authentication Methods -> SAML/OIDC is an allowed list of all email domains associated with this tenant. Only
end users from the listed email domains can sign in via this tenant's SSO authentication flow. Descope will
then block other users from authenticating.| Tenant Name | SSO Domain | User's Accessibility |
|---|---|---|
| SSO Tenant 1 | company-a.com | All end users signing in from the @mycompany-a.com email domain will be authenticated using the SSO Tenant 1 SSO authentication flow |
| SSO Tenant 2 | company-x.com, company-y.com | All end users signing in from the @mycompany-x.com or @mycompany-y.com email domains will be authenticated using the SSO Tenant 2 SSO authentication flow |
| SSO Tenant 3 | company-qqq.com, company-rrr.com | All end users signing in from the @mycompany-xqqq.com or @mycompany-rrr.com email domains will be authenticated using the SSO Tenant 3 SSO authentication flow |
Once you've done this, you can check out each of our guides, depending on whether or not you're configuring a SAML or OIDC IdP for your Tenant:
Configuring SSO with SAML
Before you start
To configure SSO within a tenant, Descope will need some configuration details from your IdP, such as the Login URL (sometimes called "SSO URL" or "Single sign-on URL"), Entity ID, and Certificate. You can configure this data in two ways:
- Dynamically retrieve the data - the IdP gives you a publicly accessible URL containing all the metadata Descope needs. Configuring via Metadata URL allows Descope to read the information dynamically, so if your IdP configuration information ever changes, Descope will automatically find the new information.
- Enter connection details manually - Copy/paste all required pieces of data manually.
All Settings
Variables are displayed below and in the console as {{variable_name}}.
| Setting | Section title in Console | Details |
|---|---|---|
| SSO Domains | Tenant Details | Email domain(s) that will use this SSO configuration. |
| JIT Provisioning | Tenant Details | Whether or not you want to override user attributes and groups with values from SAML IdP (in general this should be enabled by default, unless you want to control users via SCIM) |
| Metadata URL for IdP | Identity Provider (IdP) | URL containing all connection IdP details. You would copy this value from your IdP. |
| Login URL | Identity Provider (IdP) | URL user is redirected to for SSO authentication. This is the SSO URL or Single Sign-on URL provided from your IdP. You would copy this value from your IdP. |
| Entity ID | Identity Provider (IdP) | Unique ID assigned by your IdP. You would copy this value from your IdP. |
| Certificate | Identity Provider (IdP) | Certificate that confirms authenticity and integrity of messages shared between the IdP and SP. You would copy this value from your IdP. |
| Redirect URL | Post Authentication Redirect URL | The default URL the end user is redirected to after a successful SSO sign-in. |
| Descope XML URL | Service Provider | Service provider information sometimes required by your IdP. This item is read-only. |
| Descope Entity ID | Service Provider | The service provider entity ID is a unique identifier that represents the service provider in the SAML communication. This allows the IdP to recognize and establish a connection. |
| Descope ACS URL | Service Provider | The ACS URL is the endpoint within the service provider where the SAML response, containing the user's authentication information, is sent by the identity provider. |
| IdP user Value | SSO User Mapping | Maps IdP attributes such as email and phone |
| Groups Attribute Name | SSO Group Mapping | The name of the IdP attribute used for group association. |
| IdP Group Name | SSO Group Mapping | The name of the IdP group used for group association. |
| Descope Role | SSO Group Mapping | The Descope role you want to map the IdP group. |
Identity Provider (IdP)
The Identity Provider (IdP) section contains all the application information you registered with your IdP, including the Login URL, Entity ID, and Certificate. Descope needs these details so we can act as the SP on your behalf. Paste the information from your IdP into the console, or enter the Metadata URL if your IdP provides it.
Post Authentication Redirect URL
The Redirect URL is the default URL an end user is redirected to after a successful SSO authentication. Theredirect URL is an optional argument in the API and SDKs, and the URL provided in the API or SDK
will take precedence over the URL entered here.Note: When using IdP-Initiated Authentication with Descope flows, you must provide a Redirect URL
see here for further detail.Service Provider (SP)
The Service Provider (SP) section contains all the application information necessary to configure your application within your IDP. The data presented here are specific to the tenant you are configuring SSO for.
SSO User Mapping
SSO User Mapping maps the attributes supported by Descope to the attribute label you defined when setting up your application with your IdP. Configure as many of the supported attributes as you require. The Descope attributeEmail is required.Note: Descope also allows you to map attributes from your IdP to custom user attributes when configuring your attribute mapping.
Attribute Mapping Example
In this example, we demonstrate mapping attributes between the IdP and Descope. The table below shows the titles of the three mapped attributes mapped in the IdP console (email, login, and phone) and how you can map them
in both the IdP console and Descope console. Attributes you want to store about your end user, define it in your
IdP console and then add that attribute in the Descope console.| IdP Attributes Name | Descope Attribute |
|---|---|
| login | Display Name |
| phone | Phone Number |
Self-Service SAML Provisioning
Descope enables you to embed self-service provisioning for configuring SAML; this is implemented by adding a flow to your app. You can embed the out-of-the-boxsaml-config flow within your app. For details on Self-Service
SAML Provisioning, review our Self-Service SAML Provisioning Guide
or our Self-Service SAML Provisioning Tutorial.IdP-Initiated Authentication
IdP-initiated authentication is when you click a button or use a link provided by your IdP provider to be automatically authenticated within your application.
To configure IdP-initiated authentication within Descope, you must ensure within your IdP that your SSO URL includes the project and tenant id; if it does not, update the SSO URL within your IdP with the currentDescope ACS URL from the tenant's SSO Configuration tab.
Note: It is important to note that you must pay attention to the Redirect URL when using IdP initiated authentication, see below for details.
IdP-Initiated and Descope Flows
If you are utilizing Descope flows within your application for IdP-Initiated authentication, theRedirect URL should
land on a page that uses a flow that handles the IdP-initiated condition. The below example shows the condition using
an if/else, and if it detects IdP-initiated, it will proceed with logging into the application; however, if it does
not see IdP-initiated, it will continue to display the login screen and allow the user to log in via SP-initiated
authentication.
You can also review our IdP-Initiated Tutorial for a step-by-step
implementation of this feature.
IdP-Initiated and Descope SDK
When using IdP-Initiated authentication with the Descope SDKs, theRedirect URL should land on a page that captures
the code parameter from the URL. Your application should then exchange the SAML code via the SDK, review the SDK documentation for the process
of exchanging the SAML code.Configuring SSO with OIDC
Before you start
To configure SSO within a tenant, Descope will need some configuration details from your IdP, such as the OIDC endpoints, Client ID, and Client Secret. You can configure this data in two ways. Refer to the Settings section below, for a description of all of the things you will need.
If usingAuthorization Code grant type, you will need all of the endpoints, Client ID, and Client Secret. Otherwise if you're using the Implicit Flow (w/ Form Post) grant type, you'll just need a few of the endpoints and the Client ID.Depending on the IdP, you may or may not need to include the Issuer in your request, specify your Prompt type, or provide the JWKs (JSON web key) endpoint.All Settings
Variables are displayed below and in the console as {{variable_name}}.
| Setting | Section title in Console | Details |
|---|---|---|
| SSO Domains | Tenant Details | Email domain(s) that will use this SSO configuration. |
| JIT Provisioning | Tenant Details | Whether or not you want to override user attributes and groups with values from OIDC IdP (in general this should be enabled by default, unless you want to control users via SCIM) |
| Provider Name | Account Settings | The name of the IdP that you want to configure. |
| Client ID | Account Settings | This is the unique identifier for your application provided by the IdP. |
| Client Secret | Account Settings | A confidential secret key provided by your IdP, used in conjunction with the Client ID to authenticate your application securely. (This is not needed if using Implicit grant type) |
| Scopes | Account Settings | Define the permissions your application is requesting from the IdP. This usually includes user data scopes like email, profile, or groups. |
| Grant Type | Account Settings | Specify the OAuth 2.0 flow your application will use for authentication. For most web applications, this will be the 'Authorization Code' grant type. |
| Issuer | Connection Settings | The Issuer URI is a unique identifier for your IdP. It may be required for validating SSO responses. |
| Authorization Endpoint | Connection Settings | URL where the user is sent to log in and grant permission to your application. |
| Token Endpoint | Connection Settings | Endpoint where your application will request the access and ID tokens after the user has authenticated. |
| User Info Endpoint | Connection Settings | This endpoint provides user profile information as per the OpenID Connect standard. |
| JWKs Endpoint | Connection Settings | URL to the JSON Web Key Set (JWKs) provided by your IdP. |
| Prompt | Prompt | Specify the type of user interaction required at the IdP. |
| Attributes | User Attribute Mapping | Define how user attributes from the IdP (like email, name) should map to user attributes in Descope. This ensures correct data synchronization. |
| Callback Domain | Advanced | Specify the domain that will be used for callback responses during the SSO process. |
| Callback URL | Advanced | The callback URL that you'll need to configure in your OIDC IdP (will dynamically update with custom domain used in Descope Console) |
| Redirect URL | Advanced | Specify the default URL where users will be redirected after logging in via SSO. |
Account Settings
This section is where you will configure your Client ID, Client Secret (if applicable), and all of the necessary scopes needed for your OIDC request to your IdP.
Connection Settings
Here is where you will need to provide all of your IdP related endpoint locations. For more information on Descope's endpoints, as an OIDC provider, you can visit this docs page.
Prompt
ThePrompt option allows you to specify the type of user interaction required at the IdP. For instance, Login will force the user to enter their credentials regardless of current session status.
For more information on how Prompt works, and what you can do with this option, you can read about it under our Custom Provider page.User Attribute Mapping
User Attribute Mapping maps the attributes supported by Descope to the attribute label you defined when setting up your application with your IdP. Configure as many of the supported attributes as you require. The Descope attributeLogin ID is required.Note: Descope also allows you to map attributes from your IdP to custom user attributes when configuring your attribute mapping.
| Provider user identifier | Descope user attribute |
|---|---|
| Login ID (Required) | |
| name | Display Name |
Advanced
SSO User Mapping maps the attributes supported by Descope to the attribute label you defined when setting up your application with your IdP. Configure as many of the supported attributes as you require. The Descope attributeEmail is required.Note: Descope also allows you to map attributes from your IdP to custom user attributes when configuring your attribute mapping.