Single Sign On (SSO) with Flows
This guide will walk you through integrating SSO-based authentication into your Descope Flows. SSO allows your users to authenticate using external identity providers like Okta, Azure, and Ping Identity using either SAML or OIDC.
Our complete SSO configuration guide can be found on the overview page.
Flow Actions
When using SSO, you have only one authentication related action available. However, there are others related to configuring SSO.
- SSO - Redirects the user to their corresponding SSO provider, configured for their specific tenant.
- Generate SSO Configuration Admin Link - Generates a link that can be used with an Email Connector to be sent to a Tenant Admin.
- Revoke SSO Configuration Admin Link - Revokes access to the SSO Configuration Portal, based on the user's refresh token.
How to Use SSO Actions
To learn more about Actions in general, you can refer to our guide on them.
Most of these actions are pretty simple, and you can drop them in your application like any other Action.
This is an example of using the SSO action in a flow:
SSO Enabled Condition
If you wish for the flow to automatically handle the choice between using SSO or another authentication method like OTP with just one email input field, depending on if SSO is enabled, you can implement this using a condition block in your flow.
As an example, included in the flow above is a condition that checks if the user is ssoEnabled or not. If the user does not have SSO enabled for their tenant, it defaults to using Sign Up or In / OTP Email instead.
Flow Screens
When using SSO, you can use the either use conditions to determine if you want to redirect a user via the SSO action, or you can use the SSO button in the flow to default to using the SSO action.
If you use the SSO button with an email that is not associated with a tenant, or doesn't have SSO configured, it will return an error in the screen.
Tenant Input Components
Once you've configured a tenant name or SSO domain for your tenant, you should be able to sign in with either of them.
Tenant Name
If you wish to sign in with the name of your tenant, you can use the Tenant Domain input component:
Tenant Domain
If you wish to sign in with the SSO Domain that you configured under Authentication Methods -> SSO in your tenant configuration, you can use the Tenant Domain input component:
Using Form Context Keys in Conditions
You can utilize the values of form.tenantDomain and form.tenantName in conditions as well, which are directly fed from the respective components mentioned above.
This will allow you to create custom user experiences for specific tenants, identified by either name or domain.
Tenant Flow Parameter
Similar to how the tenant input components listed above help you associate users logging in with specific tenants, you can also use the tenant flow parameter to do the same.
This is referenced in the Client SDK reference as well, but this parameter allows you to pre-set the tenant before the flow even renders, so the flow doesn't need to rely on the user to identify the correct tenant associated with the user.
If you're embedding the Descope flow component in your app, you can just include this as a parameter in the component declaration itself. If you're using Descope Applications with our Auth Hosting application, you can read about the tenant parameter here.
Error Handling
Error handling is handled like any other action. You can refer to our Flow Error Handling guide for more details.