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 the example below, we demonstrate how to map user attributes between your Identity Provider (IdP) and Descope. The table illustrates three sample attributes email, login, and phone, and shows how they are defined in both the IdP console and the Descope console.

To store specific attributes about your end users, first configure them in your IdP console, then add the corresponding mappings 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 SSO Provisioning

Descope empowers your customers to independently configure their SSO (SAML/OIDC) integration with your application. With the Descope SSO Setup Suite, customers are guided through a step-by-step user interface to set up their SSO provider seamlessly.

Read more about the Descope SSO Setup Suite here.

IdP-Initiated SSO

For a detailed walkthrough on implementing IdP-Initiated SSO using Descope Flows and SDKs, refer to the guide here: Implementing IdP-Initiated SSO with Descope Flows.

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.