SAML Applications

When configuring a SAML Application within Descope, Descope becomes the Identity Provider for your users. This allows you to use Descope as your unified identity storage for your users across multiple applications. This guide covers how to create a SAML Application within Descope and integrate with your service provider.

Note

Configuring custom applications is an Pro/Enterprise-tier feature.

Creating a SAML Application

Within Descope, navigate to Applications and click the + Application at the top right.

When creating your application, you must provide it with an Application Name, and optionally provide an Application ID and Description.

Create a SAML Application within Descope

Configure the SAML Application

Once the SAML application has been created within the console, you can further configure the application. Below you can find the available configurations for SAML Applications within Descope.

Configuring a SAML Application within Descope

For this example, we will assume that you are building an Application within Descope to connect to ExampleServiceProvider.

All Settings

SettingSection title in ConsoleDetails
Application NameApplication DetailsThis is the chosen name of your application, this can be updated.
Application IDApplication DetailsThis is the ID of your application, this can be chosen during application creation, or is automatically populated if not provided. This can not be updated. Also, it can be used in the flow to render unique logic depending on the Application
DescriptionApplication DetailsThis is the chosen description of your application, this can be updated.
Application IconApplication DetailsBy clicking the edit button on the icon, you can provide your own icon for your SAML Application.
Flow Hosting URLSSO ConfigurationThis is the URL of the flow that the user will be redirected to when signing in with Descope as a SAML provider.
Descope XML URLSSO Configuration (Identity Provider)This is the metadata URL of your Descope SAML Application.
Download XMLSSO Configuration (Identity Provider)Clicking this allows you to download the metadata of your Descope SAML Application.
Download public certificateSSO Configuration (Identity Provider)Clicking this allows you to download the public certificate for your Descope SAML Application.
Descope Entity IDSSO Configuration (Identity Provider)This is the unique identifier of your Descope SAML Application.
SSO URLSSO Configuration (Identity Provider)This is the SSO URL you would configure within your Service Provider to link to your Descope SAML Application.
IdP-Initiated URLSSO Configuration (Identity Provider)This is the IdP-initiated SSO url that you can use to sign in with Descope into your SAML applications, starting at Descope instead of the application.
Retrieve the connection details dynamically using a metadata URLSSO Configuration (Service Provider)This is your Service Provider's metadata URL for the Descope SAML Application to dynamically retrieve the provider's details.
Enter the connection details manuallySSO Configuration (Service Provider)If you chose to configure via this route, you will provide the ACS URL, Entity ID (regex supported), any other additional authorized callback URLs, and certificate of your Service Provider.
SAML Assertion Subject TypeSSO Configuration (Service Provider) - AdvancedThe unique user identifier that you want to send back to your SP, to let it know which user is actually signing in (most commonly either Descope User ID or email)
Force AuthenticationSSO Configuration (Service Provider) - AdvancedA checkbox to enable "forced" running of a flow, regardless of if the user is already signed in or not. This behavior is akin to the SP sending prompt=login
Descope user attributeSSO Mapping (User Attribute Mapping)The Descope attribute to map to the SP user value
SP user valueSSO Mapping (User Attribute Mapping)The SP user value which the Descope attribute will be mapped to.
Descope RolesSSO Mapping (Group Mapping)The Descope roles which you'd like to map to the SAML group.
SAML XML groupSSO Mapping (Group Mapping)The SAML group you would like to map the Descope roles to.

Configure Service Provider Details

We will utilize the service provider's metadata URL, which will be https://exampleserviceprovider.com/saml/metadata; however, if you would rather, you can use the service provider's ACS URL, Entity ID (regex supported), and Certificate.

Configuring the service provider's metadata URL for a SAML Application within Descope

Advanced

SAML Subject and Name ID

Many SPs such as Zendesk, Freshworks, etc. will require that you use the user's email as the NameID subject in the SAML assertion, so they know which user has signed in with Descope. You can adjust which user attribute you wish to use for your service provider (SP), either User ID, Email, or Phone.

You can also change the NameID format of the SAML Subject, if your SP requires this. These are the currently supported NameID formats:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

This can be done by our Update SAML Application API, by updating the value for subjectNameIdFormat with the nameid-format like emailAddress or transient.

Error Redirect URL

Use this setting to provide a hosted error page for end users. This can be relevant if you want to give a custom screen when a user might experience a timeout or a misconfiguration while trying to log in with SAML SSO.

Force Authentication

By default, if Descope as a SAML provider recognizes that a user is already signed in, the user will be automatically redirected back to the SP and logged in (as per a traditional SSO experience).

However, you can check Force Authentication in the Identity Provider application configuration, to force the running of the flow regardless of if the user is already logged in or not.

Force authentication checkbox

Configure User Attribute Mapping

We will then configure the SSO Mapping for the user's attributes. We will map some of the Descope user attributes to attribute keys expected by the service provider. Below you can see an example of the email, display name, and phone number being mapped to values expected by the service provider. For this example, ExampleServiceProvider expects email, name, and phone.

Configuring user attribute mapping for a SAML Application within Descope

Configure Group Mappings

We will then configure the SSO Mapping for the groups. We will map some of the Descope groups to attribute keys expected by the service provider. Below you can see an example of groups being mapped to values expected by the service provider. For this example, ExampleServiceProvider expects groups to be mapped to the groups attribute. After configuring the group mappings, we will save our configuration of the SAML application.

Configuring group mapping for a SAML Application within Descope

Configuring Service Provider

There are three ways to configure your service provider:

  1. Metadata URL

Using metadata URLs is the easiest approach to utilize the SAML application's Descope XML URL which can be found on within the console for your SAML application. The URL would look like https://api.descope.com/v1/auth/saml/idp/metadata?projectId=xxxxx&ssoAppId=yyyy.

  1. Download the Metadata XML

You can also configure your SP with the downloaded metadata XML here:

Download Metadata XML

  1. Use Public Certificate or Fingerprint Hashes

Finally, you can configure your SP by downloading the public certificate or fingerprint hashes (if you're SP requires SHA1 or SHA256 Fingerprint Hashes) and manually copying the Descope SAML application's entity ID and SSO URL.

Fingerprint hashes and public certificate

Once you have configured your service provider per one of these methods, you are now ready to use SAML within the service provider's application.

If you're configuring your SP manually not using the metadata URL, you must at least configure a single ACS URL and Entity ID. The entity ID field supports wildcards as well, if you would like to include multiple subdomains as an Entity ID.

Mandatory SP configuration fields

Note

As you can see, you can use regex expressions in the Entity ID field.

You can also add a certificate as well as optional additional ACS URLs as well, in the field below.

Certificate and Allowed ACS URLs

Note

As you can see, you can use regex expressions in the Additional ACS URL field, and add as many additional ACS URLs as necessary.

Single Log Out (SLO)

When using Descope as a SAML provider, or as a SAML client, we support a lighter alternative to full SAML Single Log Out (SLO), similar to the Google SAML Workspace implementation.

Our implementation allows you control the Descope session, along with your SP's (Application) session. If you initiate log out from the SP, you can also choose to send an SLO assertion to Descope (according to the SAML spec) and logout of all available Descope sessions as well.

This however will not affect any other SAML SP (application) sessions connected to the same Descope project, as it would with traditional SLO.

When configuring your SAML applications, you can configure a Logout URL, which is the location you wish to your users to be redirected to after they log out of their application. Once your users have been successfully logged out of Descope, they will then be simply redirected to this URL.

SAML Single Logout Configuration

Once you've configured this URL, you'll be able to copy your IdP Logout URL from the button below, and then place this in your SAML SP. This is the endpoint you'll need to hit on our service, that will allow this whole process to begin.

This is an example IdP Logout URL:

https://api.descope.com/v1/auth/idp/sso/logout?app=<Descope Project ID>-<Descope Application ID>

IdP Initiated SSO

We have created an application that you can clone and deploy on Vercel, which will render a list of applications that a user has access to. This application allows users to use IdP-initiated SSO to sign in directly. For more details, visit the GitHub README.

Descope supports IdP-initiated SSO as a SAML provider. This means you can start from anywhere, and by navigating to the IdP-initiated SSO URL, you can step through a Descope flow, sign in, and be automatically signed into any SAML application configured with Descope.

Every SAML application will have a link like this under the Identity Provider settings: https://api.descope.com/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X.

Custom Parameters

The IdP-initiated SSO link can be customized with various query parameters to create a dynamic login experience for your users, including Tenant and Default Relay State.

Tenant

If you're more interested in use cases for this tenant parameter, please visit our SSO Applications sample application.

The Tenant parameter allows you to specify the tenant dynamically.

A common use case for this, is if you want to be able to configure authentication with multiple IdPs, into applications that only support one SAML IdP. By using IdP-initiated SSO and this tenant parameter feature, you can dynamically create one click application login links, that will redirect to any tenant you have configured, without the user having to input any information.

This value is passed into the flow hosted at your Flow Hosting URL, directing users to sign in with a specific tenant without requiring them to input their email address. You can put the tenant name, tenant id, or email address in for this value and all will work.

Example:

https://api.descope.com/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X&tenant=<tenant name, email domain, or tenant id>

Default Relay State

The Default Relay State parameter determines where users will be redirected after signing in with Descope using IdP-initiated SSO. This can be modified so different users are directed to different instances of your application.

Example:

https://api.descope.com/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X&defaultRelayState=https://example1.app.com

Use Cases for IdP-Initiated SSO with Descope

  1. Seamless Access to Multiple Applications:

    • Organizations with multiple internal applications can provide users with a single IdP-initiated SSO URL. Users can sign in once and gain access to all the applications they are authorized to use.
  2. Tailored Login Experiences for Different User Groups:

    • By using the Tenant parameter, you can direct different groups of users to specific login flows. For example, employees from different departments can be directed to tenant-specific login pages, improving user experience and security.
  3. Custom Post-Login Redirection:

    • The Default Relay State parameter allows for custom redirection after login. This is useful for organizations that want users to land on specific dashboards or application instances based on their role or department.
  4. Streamlined Partner and Vendor Access:

    • Provide partners or vendors with specific IdP-initiated SSO URLs that include the appropriate Tenant and Default Relay State parameters. This ensures they are directed to the correct application environment, reducing confusion and access issues.
Was this helpful?

On this page