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.
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
SAMLResponseto your SP's ACS URL. - Your SP validates the assertion signature using Descope's public certificate.
See Service Provider Configuration for setup details.
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.

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.
Option 1: Metadata URL (recommended)
__BaseURL__/v1/auth/saml/idp/metadata?projectId=xxxxx&ssoAppId=yyyyIf 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

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.

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.

Option 2: Manual Configuration
Provide the following values from your SP:
- ACS URL
- Entity ID (supports wildcards and regex)
- Public Certificate


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.

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

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.

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 attribute | User attribute name |
|---|---|
| Descope user email | email |
| Descope display name | name |
| Descope phone number | phone |

Group Mapping
Map Descope roles to the group attribute your SP expects.
| Descope Roles | Group attribute name |
|---|---|
Manager | Manager |

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 entry | What the assertion carries |
|---|---|
| All tenant level roles | Every 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):
usernamelogin_hintloginHintLoginHint(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.comThis 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>
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
LogoutRequestto 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 signedLogoutResponse. - 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:
- Turn on Single Logout (SLO) in the application's logout settings.
- Set the SP Single Logout URL, or leave it empty when the SP uses a metadata URL.
- Add the SP certificate, unless Descope reads it from the SP metadata.
- 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.

| Setting | Description |
|---|---|
| SP Single Logout URL | The 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 Binding | How 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 Propagation | What 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 Scope | Which 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 Logout | Whether 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
SingleLogoutServiceendpoints in the SP metadata. Descope uses SOAP when the metadata offers anhttpsSOAP 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:
- When the
SessionIndexis one that Descope issued, Descope ends that session. - Otherwise, when the request comes with the browser's Descope session, Descope ends that session. A request has no
SessionIndexfrom Descope when it has none at all, or when itsSessionIndexcomes from an assertion that Descope sent before Single Logout was on. - 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.Successwith thePartialLogoutsub-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.
| Logout | Applications Descope logs out |
|---|---|
| Force Logout of a user, from the Console or the Management API | Only 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 application | The 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 off | The 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 one | A 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 logout | Per 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 application | None |
How Descope reaches each application depends on its binding:
- SOAP: Descope sends the
LogoutRequestserver 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
PartialLogoutstatus. 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
LogoutRequestmust be signed by the SP and verify against its certificate. Otherwise Descope ends no session and answers the SP with aRequesterstatus. - Each
LogoutRequestcan be used once and must be recent, and its destination must be this application's IdP Logout URL. - The
Issuerof eachLogoutRequestmust 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-SA2hNtkVFXq3X3XUsers navigate to this URL, authenticate with Descope, and are posted directly to the SP's ACS URL — no SP redirect required.
Query Parameters
| Parameter | Description |
|---|---|
tenant | Directs users to authenticate with a specific tenant. Accepts tenant name, tenant ID, or email domain. |
login_hint / loginHint / username | Pre-fills user identity in the flow. |
RelayState | Determines where users are redirected after login at the SP. |
flow_token | A 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.comConfiguration Reference
| Setting | Section | Description |
|---|---|---|
| Application Name | Application Details | Display name of the application. Can be updated. |
| Application ID | Application Details | Unique identifier set at creation. Cannot be changed. Available in flows to render application-specific logic. |
| Description | Application Details | Optional context for the application. |
| Application Icon | Application Details | Custom icon for the application. |
| Flow Hosting URL | SSO Configuration | URL of the Descope flow users are redirected to when signing in. |
| Descope Metadata (XML) | SSO Configuration — Identity Provider | Metadata URL for your Descope SAML application. |
| Download Metadata (XML) | SSO Configuration — Identity Provider | Downloads the metadata XML for manual SP configuration. |
| Descope Entity ID | SSO Configuration — Identity Provider | Unique identifier for the Descope SAML application. |
| SSO URL | SSO Configuration — Identity Provider | The SSO URL to configure in your SP. |
| IdP-Initiated URL | SSO Configuration — Identity Provider | Entry point for IdP-initiated SSO. |
| Descope Certificate | SSO Configuration — Identity Provider | Downloads the public certificate for assertion validation. |
| Metadata URL (SP) | SSO Configuration — Service Provider | SP metadata URL for dynamic configuration. |
| Manual SP fields | SSO Configuration — Service Provider | ACS URL, Entity ID (regex supported), and SP certificate. |
| Allowed ACS Callback URLs | SSO Configuration — Service Provider — Advanced | Additional ACS URLs for multi-domain or multi-environment setups. |
| SAML Assertion Subject Type | SSO Configuration — Service Provider — Advanced | User attribute to use as the SAML subject (User ID, Email, Phone, or custom). |
| SAML Subject NameID Format | SSO Configuration — Service Provider — Advanced | NameID format sent to the SP. |
| Default Relay State | SSO Configuration — Service Provider — Advanced | Post-login redirect destination for IdP-initiated SSO. |
| Error Redirect URL | SSO Configuration — Service Provider — Advanced | Custom error page URL shown on login failures. |
| Logout URL | SSO Configuration — Service Provider — Advanced | Destination after SLO completes. |
| Single Logout (SLO) | SSO Configuration — Service Provider — Advanced | Turns on SAML Single Logout for the application. Off by default. See Single Logout. |
| SP Single Logout URL | SSO Configuration — Service Provider — Advanced | The SP's SingleLogoutService URL. Empty takes it from the SP metadata. |
| SP Single Logout Binding | SSO Configuration — Service Provider — Advanced | HTTP-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 Propagation | SSO Configuration — Service Provider — Advanced | No other apps (default) or All apps. |
| Logout Scope | SSO Configuration — Service Provider — Advanced | Current session (default) or All sessions. |
| Notify this app on Force Logout | SSO Configuration — Service Provider — Advanced | Sends 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 Authentication | SSO Configuration — Service Provider — Advanced | Forces the flow to run regardless of existing session state. |
| Descope user attribute | SSO Mapping — User Attribute Mapping | Descope attribute to map to an SP attribute name. |
| User name attribute | SSO Mapping — User Attribute Mapping | SP attribute name to receive the mapped Descope value. |
| Descope Roles | SSO Mapping — Group Mapping | Descope 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 name | SSO Mapping — Group Mapping | SAML group attribute name to receive the mapped roles. |