SSO (Single Sign-on) with SAML

We highly recommend having your customer/tenant set up SSO for their own organization using our SSO Setup Suite. The SSO Setup Suite walks your customers through the entire SSO Configuration process, with templates for all common IdPs, and allows them to test the connection, minimizing any back and forth or setup errors.

If your customer is unable to use the SSO Setup Suite for any reason, you can utilize the instructions below to configure SSO with your customer's SAML Provider.

The below configuration can be done under Authentication Methods --> SSO when you select a tenant from the Tenant tab of the Descope Console.

Configuring SSO with SAML

Before you start

To configure SSO within a tenant, you'll need to provide Descope with your IdP's configuration details.

You can provide these details in two ways:

Option 1: Metadata URL (Recommended)

If your IdP provides a metadata URL, use this method. Descope will automatically:

• Retrieve all required configuration details
• Update settings if your IdP configuration changes
• Ensure your SSO connection stays up-to-date

Option 2: Manual Configuration

Alternatively, you can manually copy and paste each required piece of information from your IdP into Descope.

All Settings

Here's a comprehensive overview of all the settings you can configure for SSO:

Tenant Details

• SSO Domains: Email domain(s) that will use this SSO configuration
• JIT Provisioning: Controls whether user attributes and groups are updated from your IdP. Enable this by default unless you're using SCIM for user management

Identity Provider (IdP) Settings

• Metadata URL: A URL containing all your IdP's connection details. This is the easiest way to configure SSO as it automatically updates if your IdP settings change
• Login URL: The URL where users are redirected to sign in (also called "SSO URL" or "Single Sign-on URL")
• Entity ID: A unique identifier for your IdP
• Certificate: The certificate used to verify the authenticity of messages between your IdP and Descope

Post-Authentication Redirect URL

• Redirect URL: The default URL where users are sent after successful sign-in. This 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) Settings

These are the settings you'll need to configure in your IdP:

• Descope Entity ID: Your unique identifier in the SAML communication
• Descope ACS URL: The endpoint where your IdP sends authentication responses
• Descope XML URL: Metadata URL for your Descope configuration (read-only)

SSO Keys

By default Descope signs the SAML request using our internal private key. However, if you prefer, you can upload your custom private key instead.

You can also override the key pair for handling the IdP SAML response encryption, with your custom private key as well.

SSO Mapping

• User Attribute Mapping: Maps IdP attributes (like email and phone) to Descope user attributes
• Group Mapping:
  • Groups Attribute Name: The attribute your IdP uses to identify groups
• RBAC Group Mapping: Map SSO Groups from your IdP to Descope roles.
  • IdP Group Name: The name of the group in your IdP
  • Descope Role: The Descope role to assign to users in this group
• Default Roles: Assign default roles to users who are automatically provisioned from your IdP with JIT.
• FGA Group Mapping: Map SSO Groups from your IdP to FGA types and relations.

SCIM Provisioning

You're able to automatically generate a SCIM Bearer token to configure SCIM with your SAML SSO IdP in this section.

The SCIM URL will automatically be populated in the SCIM URL field.

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.

You can also set this as 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 in Descope to the IdP attribute name you defined when setting up your application with your IdP. You can map as many default or custom attributes as your IdP requires.

User Attribute Mapping

In the example below, we demonstrate how to map user attributes between your Identity Provider (IdP) and Descope. As an example, the table below illustrates three 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.

We recommend testing 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