SAML Applications

Configure a Federated Application to use Descope as a SAML 2.0 Identity Provider. Your service provider redirects users to Descope for authentication, Descope runs your configured flow, and returns a signed SAML assertion. Standard SAML 2.0 protocol throughout — no custom auth logic required.

Note

Configuring additional federated applications (beyond the default) is a Pro+ feature.

Application (SP)Browser / UserDescope (IdP)access protected resourceredirect with SAMLRequestSAMLRequestauth flow runsPOST SAMLResponse to ACS URLSAMLResponsevalidate assertionsession established

The most common flow. The user tries to access a protected resource and the SP redirects them to Descope to authenticate.

  • Configure your SP with Descope's SSO URL and Entity ID from the Identity Provider section.
  • Descope runs your configured flow, then POSTs a signed SAMLResponse to your SP's ACS URL.
  • Your SP validates the assertion signature using Descope's public certificate.

See Service Provider Configuration for setup details.

1 / 3

For a full reference of all SAML application settings, see the Configuration Reference below.

Creating a SAML Application

Navigate to Federated Apps and click + Application in the top right. Choose a template from the Application Library or create a Generic SAML Application. Provide an Application Name, and optionally an Application ID and Description.

Create a SAML Application within Descope

Configuring a SAML Application

Once created, configure the application from its settings page. The two sides you need to configure are the Identity Provider (Descope's details, which you give to your SP) and the Service Provider (your SP's details, which you give to Descope).

Identity Provider Configuration

Configure your SP with Descope's details. You can use the metadata URL or enter fields manually.

__BaseURL__/v1/auth/saml/idp/metadata?projectId=xxxxx&ssoAppId=yyyy

If your SP does not support fetching metadata from a URL, download the XML file and upload it manually.

Option 2: Manual Configuration

Configure the SP manually using the following values from the Identity Provider section:

  • SSO URL
  • Entity ID
  • Public Certificate

SSO URL, Entity ID

Note

If your SP requires fingerprint hashes (SHA1 or SHA256) instead of a certificate file, Descope provides these for download as well.

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

Fingerprint hashes and public certificate

Service Provider Configuration

Configure Descope with your SP's details. You can supply a metadata URL or enter fields manually.

Option 1: Metadata URL

If your SP provides a metadata URL, Descope extracts the ACS URLs, Entity ID, and certificates automatically.

Download Metadata XML

Option 2: Manual Configuration

Provide the following values from your SP:

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

ACS URL, Entity ID

Mandatory SP configuration fields

Note

Regex expressions are supported in the Entity ID field to match dynamic or multi-subdomain configurations.

Advanced Settings

Allowed ACS Callback URLs

Specify additional ACS URLs to support logins from multiple domains or environments. Supports exact URLs and regex patterns.

Certificate and Allowed ACS URLs

Tip

Use regex for broader ACS URL coverage across staging, QA, and production environments.

SAML Subject and Name ID

Many SPs require the user's email as the NameID subject. You can choose which user attribute to use: User ID, Email, Phone, or any custom attribute. When using a custom attribute, set the NameID format to unspecified for maximum compatibility.

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

Creating a custom attribute in Descope

Setting custom attribute as NameID in SAML settings

Default Relay State

Determines where users are redirected after signing in via IdP-initiated SSO. Can be customized per application instance or user group.

Error Redirect URL

A hosted error page for end users, shown when a timeout or misconfiguration occurs during SAML login.

Force Authentication

When enabled, Descope runs the authentication flow even if the user is already signed in — equivalent to the SP sending prompt=login.

Force authentication checkbox

Note

When a user already has a valid session and Force Authentication is disabled, Descope redirects the user back to the SP without running the flow. In this case, lastAuth context keys are not populated for that request, since the flow itself was skipped.

SSO Mapping

User Attribute Mapping

Map Descope user attributes to the attribute names your SP expects in the SAML assertion.

Descope user attributeUser attribute name
Descope user emailemail
Descope display namename
Descope phone numberphone

Configuring user attribute mapping for a SAML Application within Descope

Group Mapping

Map Descope roles to the group attribute your SP expects.

Descope RolesGroup attribute name
ManagerManager

Configuring group mapping for a SAML Application within Descope

A role sent in the assertion is one the user holds in the tenant they signed in through. Roles a user holds in their other tenants are not included, so a user who is a Manager in one tenant and has no roles in another receives the attribute only when signing in through the first.

Each role becomes its own AttributeValue inside one Attribute, never a delimited string:

<saml:Attribute Name="Manager" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml:AttributeValue>Manager</saml:AttributeValue>
  <saml:AttributeValue>Supervisor</saml:AttributeValue>
</saml:Attribute>
Sending roles from every tenant

When your SP keeps one account per person rather than one per tenant, the role list should not change with the tenant a user signs in through. Two entries in the Descope Roles picker cover that, and both send the same values whichever tenant is used:

Picker entryWhat the assertion carries
All tenant level rolesEvery role in every tenant the user belongs to, each value prefixed with the tenant ID: T2MfKp9Qn4RsWxYz7BvHtLcEdUa3:Manager. Use it when the SP needs to tell the tenants apart.
All tenant level roles (role names only)The same set as bare role names, each distinct name once: Manager. Use it when the SP matches on the role itself.

Pick either one instead of listing individual roles.

Warning

Both entries drop tenant scoping, and the names-only entry also drops the tenant from the value. A role granted in any of the user's tenants then looks identical to the same role in the tenant they signed in through, so if your tenant admins can assign roles inside their own tenant, a user can obtain a privileged role name by granting it to themselves in a tenant they control. Use these entries when the SP's authorization does not depend on which tenant a role came from; otherwise map individual roles, which stays scoped to the tenant signed in through.

Between the two, the prefixed form repeats a role the user holds in several tenants and discloses every tenant ID they belong to, so prefer the names-only entry when your SP matches on the role itself.

Login Hints

Descope supports passing login hints via query parameters when initiating SAML authentication. Useful when user identity is already known before the flow begins.

Supported parameters (all behave identically):

  • username
  • login_hint
  • loginHint
  • LoginHint (used by Okta CIS)

Append to any SP-initiated or IdP-initiated URL:

__BaseURL__/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X&login_hint=user@example.com

This populates form.externalId inside the Descope flow, where it can be used in any action or condition.

Single Logout (SLO)

Single logout lets a user who signs out of one application also sign out of Descope, and, if you choose, out of their other applications.

Every SAML application has an IdP Logout URL, shown in the Console:

__BaseURL__/v1/auth/idp/sso/logout?app=<Descope Project ID>-<Descope Application ID>

Logout URL field and Copy IdP Logout URL link in a SAML application

What the IdP Logout URL does depends on the application's Single Logout (SLO) setting, which is off until you turn it on.

With Single Logout off, sending the user's browser to the IdP Logout URL is a logout of all of the user's devices, as long as the browser has a Descope session. Descope ends every Descope session of the user. OIDC applications with a back-channel logout URL get a logout token, and SAML applications with single logout over SOAP get a LogoutRequest. Descope then sends the browser to the application's Logout URL. When the browser has no Descope session, Descope ends no session, notifies no application, and only sends the browser to the application's Logout URL.

That logout doesn't send the browser through any other application on the way. SAML applications that only take the HTTP-Redirect or HTTP-POST binding need the browser, so this logout doesn't reach them.

With Single Logout on, the IdP Logout URL takes a signed LogoutRequest from the SP, as described in SAML Single Logout.

SAML Single Logout

Check that your SP supports Single Logout

Many SAML service providers, including Slack and Google Workspace, don't support SAML Single Logout. For those applications, leave SLO off and rely on the application's own session length, since a logout in Descope won't end their sessions.

Turn on Single Logout (SLO) in the application's logout settings to use standard SAML 2.0 Single Logout with the service provider:

  • The SP can log the user out: The SP sends a signed LogoutRequest to the IdP Logout URL over the HTTP-Redirect or HTTP-POST binding. Descope verifies the signature against the SP certificate (from the application settings, or the signing keys in the SP metadata). Descope then ends the sessions described in Which sessions a LogoutRequest ends and answers the SP with a signed LogoutResponse.
  • Descope logs the user out of the SP: When a logout reaches the user's applications (see Which logouts reach your applications), Descope sends the SP a signed LogoutRequest.

To set it up:

  1. Turn on Single Logout (SLO) in the application's logout settings.
  2. Set the SP Single Logout URL, or leave it empty when the SP uses a metadata URL.
  3. Add the SP certificate, unless Descope reads it from the SP metadata.
  4. Set the application's IdP Logout URL as the IdP single logout URL in your SP. With SLO on, the Descope IdP metadata advertises it for HTTP-Redirect and HTTP-POST, so an SP that reads the metadata picks it up.

Single Logout settings in a SAML application

SettingDescription
SP Single Logout URLThe SP's SingleLogoutService URL, where Descope sends logout requests and responses. Required when you configure the SP manually. Leave it empty to take it from the SP metadata.
SP Single Logout BindingHow Descope sends messages to the SP: HTTP-Redirect or HTTP-POST (through the user's browser), or SOAP (from Descope straight to the SP, requires an https URL that doesn't resolve to an internal or private address). Default picks the binding as described in SP Single Logout Binding. Use SOAP when logouts of all devices should reach this SP, since those logouts have no browser. For force logouts to reach it, also turn on Notify this app on Force Logout.
Logout PropagationWhat a logout started by this SP reaches. No other apps (default) ends only the Descope sessions that the logout names, and reaches no other application. All apps also logs the user out of their other applications. To sign the user out everywhere, pair it with the All sessions Logout Scope, since OIDC applications get a logout token only when every session of the user ended.
Logout ScopeWhich Descope sessions a LogoutRequest from this SP ends. Current session (default) ends the session the request names. All sessions ends every session of the user. See Which sessions a LogoutRequest ends.
Notify this app on Force LogoutWhether a Force Logout of a user, from the Console or the Management API, also logs the user out of this SP. A force logout has no browser, so Descope sends the LogoutRequest server to server. This setting needs single logout over SOAP: the SOAP binding, or the Default binding when it takes SOAP from the SP metadata. Descope skips an SP that takes the HTTP-Redirect or HTTP-POST binding. Off by default.

Add the SP certificate

Descope verifies every LogoutRequest against the SP certificate. A SAML application that you configure manually, with Single Logout on and no SP certificate, gives Descope nothing to verify against. Descope then refuses every logout that the SP starts, and answers the SP with a Requester status. Descope can still send that SP a LogoutRequest. To let the SP log users out, add its certificate to the application settings.

SP Single Logout Binding

The SP Single Logout Binding decides how Descope sends logout messages to the SP. When you choose HTTP-Redirect, HTTP-POST, or SOAP, Descope uses that binding. With no SP Single Logout URL set, Descope takes the URL for that binding from the SP metadata.

When you leave the binding on Default, Descope picks it:

  • With an SP Single Logout URL: Descope sends messages to that URL with HTTP-Redirect.
  • Without an SP Single Logout URL: Descope reads the SingleLogoutService endpoints in the SP metadata. Descope uses SOAP when the metadata offers an https SOAP endpoint, otherwise HTTP-Redirect, otherwise HTTP-POST.

On this page, single logout over SOAP means either the SOAP binding, or the Default binding when it picks SOAP from the SP metadata. With SOAP, Descope sends the SP its LogoutRequest server to server, so a logout without a browser can still reach the SP.

Descope answers a LogoutRequest from the SP through the browser, at an HTTP-Redirect or HTTP-POST endpoint. With the SOAP binding, or with the Default binding and SP metadata that offers only a SOAP endpoint, the SP has no such endpoint. Descope then sends no LogoutResponse after the SP sends a LogoutRequest to the IdP Logout URL. Instead, Descope sends the browser to the application's Logout URL, or to a Descope single logout error page when the application has no Logout URL.

Which sessions a LogoutRequest ends

In most cases, a LogoutRequest ends the session the SP names, and with the All sessions scope it ends every session of the user. The rules below cover the details.

A LogoutRequest names the user with a NameID, and it can name sessions with one or more SessionIndex values. While Single Logout is on, every assertion Descope sends the SP carries a SessionIndex that Descope issued for that session. Descope picks the sessions to end in this order:

  1. When the SessionIndex is one that Descope issued, Descope ends that session.
  2. Otherwise, when the request comes with the browser's Descope session, Descope ends that session. A request has no SessionIndex from Descope when it has none at all, or when its SessionIndex comes from an assertion that Descope sent before Single Logout was on.
  3. Otherwise, Descope ends every session of the user that the NameID names.

When the request has several SessionIndex values, Descope ends each one that Descope issued. When any of them isn't one that Descope issued, Descope follows the third rule and ends every session of the NameID's user. With the All sessions scope, the first two rules also end every session of the user, so a LogoutRequest from that SP always ends every session of the user.

In every case, the user must be the one the NameID names to this application, and the user must be able to sign in to the application. Descope answers the SP with one of these statuses, unless the SP has no endpoint for an answer, as described in SP Single Logout Binding:

  • Success: Descope ended the sessions that the request names.
  • Success with the PartialLogout sub-status: Descope couldn't match the request to a user and ended no session, or another application in the logout answered with an error.
  • Requester: The request failed one of the security requirements, and Descope ended no session.
  • Responder: Descope couldn't read the user, and ended no session.

Which logouts reach your applications

Whether a logout reaches the user's other applications depends on where the logout starts. In the table below, the user's applications are every SAML application with SLO on, and every OIDC application with a back-channel logout URL, that the user can sign in to.

LogoutApplications Descope logs out
Force Logout of a user, from the Console or the Management APIOnly the user's applications with Notify this app on Force Logout on: OIDC applications with a back-channel logout URL, and SAML applications with single logout over SOAP. With the setting off on every application, a force logout ends only the user's Descope sessions.
Logout of all devices in your applicationThe user's applications that Descope can reach without a browser: OIDC applications with a back-channel logout URL, and SAML applications with single logout over SOAP.
A visit to a SAML application's IdP Logout URL, with Single Logout offThe same applications as a logout of all devices, when the browser has a Descope session. Without one, no application. The browser then goes to the application's Logout URL and visits no other application on the way.
A logout that a SAML application starts, with Single Logout on: a LogoutRequest from the SP, or a visit to the IdP Logout URL without oneA visit without a LogoutRequest ends every Descope session of the user when the browser has a Descope session, and the browser then goes to the application's Logout URL. A LogoutRequest ends the sessions described in Which sessions a LogoutRequest ends. Other applications are reached per that application's Logout Propagation. With No other apps (the default), no other application. With All apps, the user's other applications, including SAML applications that only take HTTP-Redirect or HTTP-POST. OIDC applications get a logout token only when every session of the user ended.
An OIDC application's end-session logoutPer that application's Logout Propagation. With No other apps (the default), only that application gets a logout token. With All apps, the user's other applications also log out. SAML applications that only take HTTP-Redirect or HTTP-POST log out only when the end-session request has a post_logout_redirect_uri, since they need the browser.
Logout of the current session, or of chosen sessions, in your applicationNone

How Descope reaches each application depends on its binding:

  • SOAP: Descope sends the LogoutRequest server to server, in the background, so the logout doesn't wait for it.
  • HTTP-Redirect and HTTP-POST: Both bindings need the user's browser. During a browser logout, Descope sends the browser to each such application in turn before the final redirect. If one of them answers with an error, the SP that started the logout gets a PartialLogout status. Three logouts don't send the browser through other applications: a Force Logout, a logout of all devices, and a visit to the IdP Logout URL with Single Logout off. Those logouts skip these applications.

What the SP receives

The LogoutRequest names the user with the same NameID value and format as the application's assertions. Its SessionIndex names the Descope session. When every session of the user ended, the request has no SessionIndex, and the SP should end all of that user's sessions.

Every application the user can sign in to

A logout that reaches the user's applications sends a LogoutRequest to every application with SLO on that the user can sign in to, including ones the user hasn't used, and each request names the user by that application's NameID, which can be the user's email or phone. To limit which applications a user's logout reaches, assign applications to users explicitly and deny applications by default in your project settings.

Security

  • A LogoutRequest must be signed by the SP and verify against its certificate. Otherwise Descope ends no session and answers the SP with a Requester status.
  • Each LogoutRequest can be used once and must be recent, and its destination must be this application's IdP Logout URL.
  • The Issuer of each LogoutRequest must be the SP's Entity ID, from the application settings or the SP metadata.
  • The NameID of each LogoutRequest, when present, must be the one the user has with the application, and the user must be able to sign in to the application.

IdP-Initiated SSO

Every SAML application has an IdP-initiated URL under the Identity Provider settings:

__BaseURL__/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X

Users navigate to this URL, authenticate with Descope, and are posted directly to the SP's ACS URL — no SP redirect required.

Query Parameters

ParameterDescription
tenantDirects users to authenticate with a specific tenant. Accepts tenant name, tenant ID, or email domain.
login_hint / loginHint / usernamePre-fills user identity in the flow.
RelayStateDetermines where users are redirected after login at the SP.
flow_tokenA single-use token from an Embedded Link (generated via the Management SDK) or a test-user Magic Link (generated via the Management SDK's test-user endpoint). Validate it with the Verify Token action. Any custom claims on the token land on the flow's customClaims context value as a JSON string. Parse the claims (for example with a Scriptlet) into an object and store it under its own context key before pointing Add SAML Attributes's "Context Key for SAML Attribute Map" at it; Add SAML Attributes can't read customClaims directly.

Note

The IdP-initiated URL recognizes only the parameters listed above. Descope doesn't forward other query parameters into the flow.

Example with tenant and login hint:

__BaseURL__/v1/auth/saml/idp/initiate?app=P2NvMv9S3-SA2hNtkVFXq3X3X&tenant=corp&login_hint=user@example.com

Configuration Reference

SettingSectionDescription
Application NameApplication DetailsDisplay name of the application. Can be updated.
Application IDApplication DetailsUnique identifier set at creation. Cannot be changed. Available in flows to render application-specific logic.
DescriptionApplication DetailsOptional context for the application.
Application IconApplication DetailsCustom icon for the application.
Flow Hosting URLSSO ConfigurationURL of the Descope flow users are redirected to when signing in.
Descope Metadata (XML)SSO Configuration — Identity ProviderMetadata URL for your Descope SAML application.
Download Metadata (XML)SSO Configuration — Identity ProviderDownloads the metadata XML for manual SP configuration.
Descope Entity IDSSO Configuration — Identity ProviderUnique identifier for the Descope SAML application.
SSO URLSSO Configuration — Identity ProviderThe SSO URL to configure in your SP.
IdP-Initiated URLSSO Configuration — Identity ProviderEntry point for IdP-initiated SSO.
Descope CertificateSSO Configuration — Identity ProviderDownloads the public certificate for assertion validation.
Metadata URL (SP)SSO Configuration — Service ProviderSP metadata URL for dynamic configuration.
Manual SP fieldsSSO Configuration — Service ProviderACS URL, Entity ID (regex supported), and SP certificate.
Allowed ACS Callback URLsSSO Configuration — Service Provider — AdvancedAdditional ACS URLs for multi-domain or multi-environment setups.
SAML Assertion Subject TypeSSO Configuration — Service Provider — AdvancedUser attribute to use as the SAML subject (User ID, Email, Phone, or custom).
SAML Subject NameID FormatSSO Configuration — Service Provider — AdvancedNameID format sent to the SP.
Default Relay StateSSO Configuration — Service Provider — AdvancedPost-login redirect destination for IdP-initiated SSO.
Error Redirect URLSSO Configuration — Service Provider — AdvancedCustom error page URL shown on login failures.
Logout URLSSO Configuration — Service Provider — AdvancedDestination after SLO completes.
Single Logout (SLO)SSO Configuration — Service Provider — AdvancedTurns on SAML Single Logout for the application. Off by default. See Single Logout.
SP Single Logout URLSSO Configuration — Service Provider — AdvancedThe SP's SingleLogoutService URL. Empty takes it from the SP metadata.
SP Single Logout BindingSSO Configuration — Service Provider — AdvancedHTTP-Redirect, HTTP-POST or SOAP. Default: with an SP Single Logout URL, HTTP-Redirect. Without one, from the SP metadata (SOAP when it offers an https SOAP endpoint, else HTTP-Redirect, else HTTP-POST).
Logout PropagationSSO Configuration — Service Provider — AdvancedNo other apps (default) or All apps.
Logout ScopeSSO Configuration — Service Provider — AdvancedCurrent session (default) or All sessions.
Notify this app on Force LogoutSSO Configuration — Service Provider — AdvancedSends the SP a LogoutRequest when the user is force logged out. Requires single logout over SOAP: the SOAP binding, or the Default binding when it takes SOAP from the SP metadata. Off by default.
Force AuthenticationSSO Configuration — Service Provider — AdvancedForces the flow to run regardless of existing session state.
Descope user attributeSSO Mapping — User Attribute MappingDescope attribute to map to an SP attribute name.
User name attributeSSO Mapping — User Attribute MappingSP attribute name to receive the mapped Descope value.
Descope RolesSSO Mapping — Group MappingDescope roles to map to a SAML group attribute, or one of the two All tenant level roles entries to send the user's roles from every tenant.
Group attribute nameSSO Mapping — Group MappingSAML group attribute name to receive the mapped roles.
Was this helpful?

On this page