SSO (Single Sign-On)

Descope supports both SAML 2.0 and OAuth 2.0 specifications for Single Sign-On (SSO), allowing you to integrate with any identity provider (IdP) that implements either standard. To get started with SSO:

1. Enable SSO in your project by navigating to Authentication Methods --> SSO
2. Select "Service Provider" and toggle it on
3. Configure SSO settings for each tenant individually through the Tenants page

SSO Acronyms

Here are the key terms you'll encounter when setting up SSO:

• Identity Provider (IdP): Your SSO provider (like Okta, Azure AD, or Google Workspace) that handles user authentication
• Service Provider (SP): Your application that users want to access. With Descope, you don't need to implement the complex SP side of SSO - we handle that for you.

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.

Tenant Identification Methods

No matter which authentication method your IdP uses, you have multiple options for identifying which tenant a user belongs to:

Since SSO configuration is managed at the tenant level, you need to define how users are linked to their specific tenant before they can authenticate with the appropriate IdP.

Option 1: SSO Domains (Optional)

You can configure SSO domains under Tenants -> Select Tenant -> Authentication Methods -> SAML/OIDC. This creates an allowed list of email domains associated with this tenant. When configured, only end users from the listed email domains can sign in with this tenant's associated SAML/OIDC identity provider (IdP).

Option 2: Tenant Slug or ID

If you have users from multiple domains in a single tenant, or if you cannot use domain association with your SSO provider, you can use the tenant slug or ID instead. This can be passed through the flow component, allowing you to route users to the correct tenant regardless of their email domain.

When using tenant slugs or IDs, you don't need to configure SSO domains. This is particularly useful when:

• Multiple domains exist within a single tenant
• Your SSO provider doesn't support domain-based routing
• You want more flexibility in how users are assigned to tenants

Once you've chosen your tenant identification method, you can check out the following guides, depending on whether you're configuring a SAML or OIDC SSO provider for your Tenant:

• Configuring SAML SSO
• Configuring OIDC SSO

General SSO Configuration

These settings apply to all tenants using SSO in your project. You can configure them in the Descope Console under Authentication Methods --> SSO settings.

Convert Existing Users to SSO-only

When enabled (default), this setting determines how users are converted to SSO-only authentication. This means that once a user successfully authenticates via SSO, they will only be able to sign in using SSO in the future. Here's what happens in different scenarios:

What You Should Know

1. When Tenant Exists Before User:

   • If a tenant is already set up with a domain association
   • And a user signs in with an email matching that domain
   • The user will be added to the tenant
   • If the tenant later enables SSO, and the user signs in via SSO
   • The user will be converted to SSO-only authentication

2. When User Exists Before Tenant:

   • If a user already has an account before a tenant is created
   • And that tenant is later created with domain/SSO
   • The user won't be automatically associated with the tenant
   • If the user tries to sign in via SSO with the same email
   • A new SSO-only account will be created, resulting in duplicate accounts

Auto-Association Configuration

To handle the "User Created First" scenario, you can enable auto-association in your specific tenant settings:

• Email Domain Auto-Association: Automatically associate existing users with matching email domains to newly created tenants
• SSO Domain Auto-Association: When enabled, existing users will be:
  • Associated with the tenant if their email matches the SSO domain
  • Converted to SSO users when they first authenticate via SSO
  • Merged with their existing account instead of creating a duplicate

Post Authentication Redirect URL

• Default Redirect URL: The URL where users are redirected after successful SSO authentication. This can be:
  • A static URL (e.g., https://myapp.com/dashboard)
  • A dynamic URL using tenant information:
    • {{tenant.domain}} - The tenant's domain
    • {{tenant.name}} - The tenant's name
    • {{tenant.selfProvisionDomain}} - The email domain that allows tenant self provisioning

Example of a dynamic redirect URL in action:

This can be overridden by:

• Tenant-specific redirect URLs
• URLs specified in the SDK or API calls

User Attributes

• Mandatory User Attributes: Define which Descope user attributes must be populated when receiving SSO information. This ensures that your SSO configuration provides all necessary user data.

Fine-Grained Authorization (FGA)

• Mappable FGA Types: Select which FGA schema types are available for tenant admins to use when mapping SSO groups. This controls which types of access control can be managed through SSO group mappings.

SSO Setup Suite Configuration

The SSO Setup Suite allows your customers to self-configure their SSO integration. These settings control how the suite works across all tenants.

Access Control

Configure who can access and use the SSO Setup Suite:

• FGA Permission: Required FGA permissions to access the suite

Styling

You can apply a custom style for the SSO setup suite, that can customize the appearance of the SSO Setup Suite to match your brand.

Invitation Configuration

Control how users are invited to set up SSO:

• Connector: Which email connector to use for sending the invitation email.
• Email Template: Customize the invitation email content and design
• Expiration: Set how long the SSO Setup Suite invitation remains valid

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 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 OIDC SSO, you'll need to gather some information from your IdP. The exact requirements depend on which OAuth 2.0 flow you're using:

Authorization Code Flow (Recommended)

You'll need:

• Client ID and Client Secret
• All OIDC endpoints (Authorization, Token, User Info, JWKs)
• Optional: Issuer URL and Prompt type

Implicit Flow with Form Post

You'll need:

• Client ID
• Authorization and User Info endpoints
• Optional: Issuer URL and Prompt type

All Settings

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

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

Account Settings

• Provider Name: The name of your IdP (e.g., "Okta", "Azure AD")
• Client ID: Your application's unique identifier from the IdP
• Client Secret: A confidential key from your IdP (not needed for Implicit Flow)
• Scopes: Permissions your app requests from the IdP (e.g., email, profile, groups)
• Grant Type: The OAuth 2.0 flow to use:
  • Authorization Code
  • Implicit Flow with Form Post

Connection Settings

• Issuer: Your IdP's unique identifier (required by some providers)
• Authorization Endpoint: Where users are sent to log in
• Token Endpoint: Where your app requests access and ID tokens
• User Info Endpoint: Where your app gets user profile information
• JWKs Endpoint: Where your app gets public keys for token verification

Prompt

• Prompt: Controls the login experience at your IdP:
  • login: Force users to log in
  • consent: Force users to grant permissions
  • none: Use existing session if available

SSO Mapping

• User Attribute Mapping: Map IdP attributes to Descope user attributes:
  • email → Email
  • name → Display Name
  • picture → Profile Picture
  • etc.

SCIM Provisioning

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

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

Advanced Settings

• Manage tokens from provider: If enabled, Descope will manage the OAuth tokens from your IdP.
• Callback Domain: The domain for SSO callback responses
• Callback URL: The URL your IdP will call after authentication
• Redirect URL: Where users go after successful login

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.