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.

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.

The SSO 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.

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
• Configuring SSO with OIDC

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:

1. 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.

2. 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}}.

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. The redirect 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.

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 attribute Email is required.

User Attribute Mapping

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.

Group Mapping

Group Mapping is a key feature in Descope's SSO solution, allowing you to integrate role-based access control from your IdP into your Descope-powered application.

How Group Mapping Works

Descope enables you to map groups defined in your IdP to roles within your Descope-powered applications.

1. Define Groups in Your IdP: Groups are typically defined in your IdP, representing organizational units, roles, or departments (e.g., "Engineering," "HR," "Sales").
2. Map Groups to Roles in Descope: Use the Descope Console to create role mappings that associate each IdP group with a corresponding role in Descope. For example, the "HR" group in your IdP can map to an "HR Team" role in Descope.
3. Automatic Role Assignment on Login: When users authenticate through SSO, Descope receives group information from the IdP, then automatically assigns them the appropriate role based on the mappings you’ve configured.
4. Access Control Based on Roles: Roles defined in Descope then dictate what permissions and resources are available to the user within your application, allowing for efficient, centralized access control.

Configuring Group Mapping

To set up group mapping in Descope, follow these steps:

Step 1: Define Roles in Descope

1. Log into your Descope Console.
2. Navigate to Tenant Management and select the tenant where you want to set up group mappings.
3. Under Roles & Permissions, define roles that correspond to the groups in your IdP. For example, create roles like "Finance Team" or "Engineering Lead" to match your organization’s structure.

Step 2: Map IdP Groups to Descope Roles

1. In the SSO Configuration tab for the selected tenant, locate the Group Mapping section.
2. Specify the Groups Attribute Name – the attribute in your IdP that identifies user groups (e.g., "groups" for Azure AD).
3. Map each IdP group (e.g., “Engineering”) to a specific Descope role (e.g., “Developer Team”) by entering the IdP Group Name and selecting the corresponding Descope Role.

Tip: Test each mapping after configuration to verify that users in the IdP group are assigned the correct roles in Descope.

Using Group Mapping with Other IdPs

You can also configure group mappings for other IdPs, such as Okta and Google Workspace, following similar steps. Ensure you check each IdP's documentation on enabling group claims in SAML assertions or OIDC tokens.

For more guidance, explore these resources:

• Azure AD Group Mapping: Configuring Group Claims in Azure AD
• Okta Group Mapping: How to Map Groups in Okta
• Descope Role Management: Managing Roles in Descope

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-box sso-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 current Descope ACS URL from the tenant's SSO Configuration tab.

IdP-Initiated and Descope Flows

If you are utilizing Descope flows within your application for IdP-Initiated authentication, the Redirect 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, the Redirect 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 using Authorization 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}}.

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

The Prompt 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.

Attribute Mapping Best Practices

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 attribute Email is required.