Self-Service SSO Configuration
Descope offers a self-service configuration flow that allows the administrators of your tenants to be able to configure their own SAML/OIDC external IdPs with Descope.
This can be done without any interaction with a Descoper (administrator of the Descope Console).
Every Descope project comes with this flow by default, which contains interactive guides for configuring a variety of IdPs.
SSO Configuration Example
The video below will walk you through the experience of configuring an IdP using the Self-Service Configuration feature.
Identity Providers (IdPs) Supported
Descope supports any SAML/OIDC providers. However, we have dedicated guides specific to a subset of IdPs available out of the box with the config panel.
Built-in Setup Guides
Note
To request another specific guide, you can do so on our Feature Request portal.
- Okta
- Google Workspace
- Entra ID (Azure AD)
- JumpCloud
- PingOne
- OneLogin
- Salesforce
- PingFederate
- CyberArk
Custom SAML/OIDC Wizard
If you are using another SAML/OIDC provider that is not mentioned in the list above, we also have a custom setup wizard for any other IdPs that follow the SAML/OIDC standards.
This includes attribute/group mapping, as well as SAML/OIDC testing capabilities as well.
Features
The SSO self-service configuration feature can do the following actions:
- Configure SAML/OIDC external IdPs
- Map user and group attributes from the IdP to Descope
- Configure SSO Domains for tenants
- Test SAML/OIDC SSO provider login on demand
Ways to Use This Feature
There are a couple of different ways to use this feature. Both are outlined in this section below.
SSO Configuration Link
The feature invokes the sso-config
from the flows library.
The most popular method for allowing tenant admins to configure their own SSO, is for you as a Descoper to send them a SSO Configuration link
.
This feature generates a time-based link to the tenant's SSO settings, allowing your users to avoid worrying about permissions and maintenance.
Automating Sending the Link
You can use the Generate SSO Configuration Link
action in a flow, when you're creating a tenant and building your onboarding flow as well.
This will allow you to automate the sending of the link, instead of generating it in the Descope console yourself and sending it to your tenant admins.
Using the API/SDK
You can use the API to generate the SSO Configuration Link. or use the SDK:
Also, you can use the API to revoke the SSO Configuration Link once it is no longer needed.
Embedding the Configuration Widget in a Custom Application
If you would prefer, you can embed the SSO configuration widget within your application.
A user will have to be signed in with a JWT that contains the SSO Admin
permission, to be able to use it.
Once authenticated, the user will be able to see the same experience as our internal feature, allowing them to configure their tenant's SSO settings.
Upon navigating to this page, you need to validate the user has the applicable role before displaying the flow. Below are examples of how to embed the flow using our SDKs.
User SSO Admin Permission
If you're embedding the self-service SSO configuration widget, you'll need to associate a user with the SSO Admin
permission in order to use it.
Either create or modify a user to associate them with the Tenant Admin
role or another role with the SSO Admin
Permission.
This can either be done within the Descope Console, or with the management SDK or API.
Here is an example of a user associated with the Tenant Admin
role, which has the SSO Admin
permission within the Descope console:
Using the SSO Configuration Widget
This section demonstrates how the user will step through the SSO Self-Service configuration portal.
Selecting your Identity Provider (IdP) or Protocol
You can select a provider with detailed instructions in a specific setup guide, or configure generic SAML/OIDC directly.
User / Group Attribute Mapping
Next, you'll need to make sure that all of the proper user and group attributes are mapped accordingly in Descope.
User attributes are mapped based on the claim name that is configured and sent from the external IdP.
Group names can be mapped to pre-configured roles in Descope. If you wish to create more roles under a specific tenant to map to, you'll need to do that from within the console first, before having the tenant admins run through this configuration widget.
If you wish to learn more about Group Mapping, you can visit our docs page on it here
Configuring SSO Domains
The final step is to configure the tenant's SSO company domain. This domain is utilized during the SSO flow action, will automatically redirect users to the tenant based on the domain in their email address.
Testing SSO Connection
Once you've walking through the SSO configuration setup process, you'll be taken to a screen that allows you to go back and change various configurations in the future. If you wish to test the SSO connection that has just been setup, you can click the Test button.
This will redirect you to the proper IdP and allow you to sign in. On your return, you'll see the SAML assertion, along with any errors if there were any, relating to the user/group attribute mapping.
If there was some error in the initial setup process (not the user/group mapping), you'll see the error screen when you select Test instead of a redirect.
Account Recovery Login ID Flow
By default, once the Tenant Admin
logs in successfully via SSO, their original login ID that was added by the Descoper (Descope Console admin) will be replaced with the SSO-specific one.
This can be controlled via a flag in the Descope Console, under Authentication Methods -> SSO -> Convert existing user to SSO-only after successful SSO login
, and is enabled by default to essentially force SSO-based login in the future for the Tenant Admin user.
However, if you're hosting the sso-config
flow above in your own application and a Tenant Admin makes an accidental change to the SSO configuration, this can prevent them from logging in and changing the SSO Configuration back to the correct settings.
Therefore, if SSO login is rendered inoperational as a result of this, you can add the ability to verify and merge an additional email login ID to the user by including the Update User
action in the flow like so:
When you add an Update User / Email
action to the flow, this will allow you to verify and re-add their original email back as a login ID. Or, you can do an Update User / OAuth
action to add social login as an additional login ID as well.
You will need to make sure you select Add to Login IDs
under the Update User
action, in order for the login IDs to be merged:
Migrating SSO Tenants to Descope
If you have a previous SSO setup with a different authentication provider or a home-grown solution, usually, the tenant's IT management team is forced to re-configure the setup within their IdP to match the new authentication provider. This can cause a lot of friction and unnecessary time consumption, especially when this process requires reaching out to the customers, changing, and testing the authentication.
To prevent this friction, Descope supports the ability to consume and eventually migrate the current customer's setup.
Follow this documentation to seamlessly migrate SSO tenants to Descope.
Conclusion
At this point, SSO is now configured within your tenant and ready to be used. Your tenant members should now be able to sign in with SSO.
If you do not support SSO login in your flow yet, read more about the SSO authentication method here.