Project-Level SSO Settings

These settings apply to all tenants using SSO in your project. You can configure them in the Descope Console under Authentication Methods --> SSO settings, or as code with Terraform (authentication.sso / sso_suite_settings).

General Settings

SSO General Settings

Convert Existing Users to SSO-Only

When enabled (the default), this setting controls how users become SSO-only. Once a user authenticates through SSO, they can only sign in with SSO afterward.

To ensure that SSO/SCIM merging occurs, the existing user must belong to a single tenant that is configured with SSO.

What You Should Know

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
When User Exists Before Tenant: If a user already has an account before a tenant is created and that tenant is later created with the same domain/SSO configuration for that domain, 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

email domain

sso domain

Note

Auto-association helps prevent duplicate accounts by merging existing users with their SSO identities when the email addresses match. This is particularly useful when users have existing accounts with personal emails that later become their SSO email addresses.

Allow Duplicate SSO Domains Across Tenants

When multiple tenants share the same SSO domain, such as different departments within the same organization, you must give users a way to select their specific tenant before initiating SSO authentication.

To support this, make sure the Allow duplicate SSO domains across tenants setting is enabled. Then, follow the steps in our flow guide to allow the user to select the tenant they want to authenticate into.

When enabled, Descope validates that the email address returned by the Identity Provider (IdP) during SSO authentication belongs to one of the domains configured for that SSO connection. If the email domain does not match, the login attempt is blocked and the flow fails.

This setting applies to both SAML and OIDC SSO connection types.

By default, Descope trusts the email field returned by the IdP as-is. In most setups this is fine, but in multi-tenant or federated IdP environments, a single IdP can issue tokens for users across many domains. Without domain validation, a user whose IdP email happens to belong to an unexpected domain could complete SSO login when they shouldn't.

Enabling this setting provides a built-in enforcement layer so you do not need to add a custom scriptlet to your flow to inspect and block mismatched emails.

Note

This is a project-level setting. It applies to all tenants and both SAML and OIDC SSO connections within your project. Make sure each tenant's SSO Domains list is correctly configured before enabling this — if SSO domains are not set for a tenant, logins for that tenant may be blocked unexpectedly.

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.id}} - The tenant's unique ID
  - {{tenant.selfProvisionDomain}} - The email domain that allows tenant self provisioning

SSO dynamic redirect URL configuration

Example of a dynamic redirect URL in action: SSO dynamic redirect URL example

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 (and the SSO Setup Suite) when mapping SSO groups to FGA relations. This does not create the maps themselves. It only limits which types appear in the pickers.

How to define IdP group → FGA relation maps (fgaMappings / ReBAC groups mappings): SSO user and group mapping → Groups → FGA.

Note

These general settings apply to SSO across your whole project. Individual tenants can also have their own configuration on top of them.

SSO Setup Suite Settings

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

SSO Setup Suite Settings

Access Control

Configure who can access and use the SSO Setup Suite:

RBAC Permissions: Defines the permissions assigned to the SSO Suite user, which influence the available roles shown in the group mapping section.
FGA Permission: Required FGA permissions to access the suite

FGA Resource Tenant ID

This setting applies at the project level. Configure it once, and it covers how Descope looks up FGA resources for every tenant in the group → FGA mapping picker, in both the SSO Setup Suite and the Console.

SSO FGA Resource Tenant ID

Descope replaces the {{tenantID}} placeholder with each tenant's raw ID during that lookup. If your FGA relations store tenant-scoped resource IDs with a fixed prefix and/or suffix (for example org:<tenantID> instead of <tenantID>), set Prefix and/or Suffix here to match.

Note

Prefix and Suffix only affect that resource lookup. The Default Relations fallback (see Groups to FGA Relations) substitutes {{tenantID}} on its own, ignoring Prefix and Suffix.

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.

SSO Suite Features

You can specify the enabled functionalities of the SSO Setup Suite. Choose whether or not to include SAML, OIDC, SCIM Configuration, Group Mapping, and/or SSO Domains.

Force Domain Verification

Require the SSO Setup Suite User to verify their domain before configuring SSO for their tenant.

To complete the verification, the SSO Setup Suite User will need to add a DNS TXT record. Configuration details are available within the SSO Domains tab of the SSO Setup Suite.

SSO Setup Suite Domain Verification

Show Help Contact

Add a support email address that will be displayed within the SSO Setup Suite UI. When configured, IT admins will see this contact information throughout the setup process, giving them a clear path to reach out if they encounter any issues.

SSO Setup Suite Help Contact

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

Was this helpful?

On this page