SAML Applications

When configuring a Federated SAML Application, Descope acts as the federated identity provider for your application.

This enables you to use Descope as a centralized identity store for your users across multiple applications.

Creating a SAML Application

Within Descope, navigate to Federated Apps and click + Application on the top right.

You can choose a template from our Application Library, or create a Generic SAML Application. When creating your application, you must provide it with an Application Name, and optionally provide an Application ID and Description.

Configuring a SAML Application

Once the SAML application has been created within the console, you can configure the application.

If you'd like to skip to an in-depth look at all of the settings, go to the Service Provider Configuration section below.

All Settings

Identity Provider Configuration

To configure your SAML service provider (SP) to federate with Descope, use the details available under the Identity Provider Configuration section in the Descope Console. You can either use the metadata URL or manually enter the required fields.

Option 1: Metadata URL

The recommended approach is to use the Descope metadata URL, which provides all necessary configuration details automatically:

https://api.descope.com/v1/auth/saml/idp/metadata?projectId=xxxxx&ssoAppId=yyyy

If your SP doesn't support fetching metadata from a URL, you can download the XML file and upload it manually.

Option 2: Manual Configuration

If metadata cannot be used, configure the SP manually using the following values:

• SSO URL
• Entity ID
• Public Certificate

These are provided in the Identity Provider Configuration section of the console.

You may also choose to upload a custom certificate to replace the default Descope certificate.

Service Provider Configuration

Unlike OIDC, SAML requires configuration on both sides: the Identity Provider (IdP) and the Service Provider (SP). After configuring your SAML application with Descope's IdP details, you’ll need to configure your SP settings within Descope.

You can do this by either supplying your SP's metadata URL or by entering the ACS URL, Entity ID, and certificate manually.

Option 1: Metadata URL

If your SP provides a metadata URL, this is the simplest and fastest way to configure the SP in Descope. All necessary details—including ACS URLs, Entity ID, and certificates—are extracted automatically.

If your SP doesn't support metadata fetching, you can download and upload the XML file manually.

Option 2: Manual Configuration

If metadata isn't available, configure the SP manually by providing the following:

• ACS URL
• Entity ID (supports wildcards and regex)
• Public Certificate

These values must be entered into Descope to establish a valid SAML connection.

At a minimum, you must provide a single ACS URL and Entity ID for manual configuration. The Entity ID field supports wildcard patterns if your SP operates across multiple subdomains.

Advanced Settings

Allowed ACS Callback URLs

You can specify additional ACS URLs to support logins from multiple domains or environments. This field supports both exact URLs and regex patterns.

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 choose which user attribute you wish to use for your service provider (SP): either User ID, Email, Phone, or any custom attribute. When using a custom attribute, it's recommended to set the NameID format to unspecified to ensure maximum compatibility.

You can also change the NameID format of the SAML subject, if your service provider (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

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.

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.

SSO Mapping

User Attribute Mapping

Use the Add button to map Descope user attributes to the attribute names expected by your service provider (as SAML attributes).

For example:

Group Mapping

Use the Add button to map Descope roles or groups to the group attribute expected by your service provider.

For example:

Customizing SAML Requests with Login Hints

Although not part of the SAML specification, Descope supports the ability to pass login hints via query parameters when initiating SAML authentication. This is useful for scenarios where user identity is already known prior to starting the authentication flow — such as when Descope is used purely for MFA or identity augmentation.

Supported Query Parameters

Descope recognizes the following query parameters for login hints:

• username
• login_hint
• loginHint
• LoginHint - used by Okta CIS

Each of these parameters is interpreted the same way. You can use any of them to pass a user identifier (such as email, phone number, or user ID) to Descope before the flow begins.

If you're using IdP-initiated SSO or SP-initiated SSO, you can append a login hint like so:

https://api.descope.com/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X&login_hint=user@example.com

This will result in form.externalId being populated with user@example.com inside the Descope flow. You can then use it with any action or reference it with any condition.

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.

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

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.

Use Cases for IdP-Initiated SSO

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.

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, Login Hint, and Default Relay State.

Tenant

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>

Login Hint

As with the traditional SP-initiated SSO, you can use the login hint parameter to pass a user identifier (such as email, phone number, or user ID) to Descope when using IdP-initiated SSO. See the Customizing SAML Requests with Login Hints section above for more details.

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