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:

// The expiration parameter takes a number to add in milliseconds to the current time now.
const link = await descopeClient.management.tenant.generateSSOConfigurationLink('tenant-id', 3000);

// The expiration parameter takes a number to add in milliseconds to the current time now.
tenantID := "tenant-id"
res, _err := descopeClient.Management.Tenant().generateSSOConfigurationLink(ctx, tenantID, 3000)

Also, you can use the API to revoke the SSO Configuration Link once it is no longer needed.

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.

import { Descope, useSession, useUser, getJwtPermissions, getSessionToken } from '@descope/react-sdk';
import { useNavigate } from "react-router-dom";
 
const SsoSetup = () => {
  const { isAuthenticated, isSessionLoading } = useSession()
  const { isUserLoading } = useUser()
  const permissions = getJwtPermissions(getSessionToken(), 'T2TkjYGrVh6ngFjInykigfBzYQIx')
  const isSSOAdmin = permissions.indexOf("SSO Admin") > -1
  const navigate = useNavigate();
 
  if (!isAuthenticated) {
    console.log("Redirect to login page");
    // Handle redirect to login page here
    return null;
  }
 
  if (!isSSOAdmin) {
    console.log("Redirect to another authenticated page");
    navigate("/");
    return null;
  }
 
  return (
    <Fragment>
      { isSSOAdmin &&
        <div className="data-table-wrapper">
          <div style={{ margin: 'auto', maxWidth: '450px', borderRadius: "10px", overflow: "hidden", width: "100%" }}>
            <Descope
              flowId="sso-config"
              onSuccess={(e) => {
                navigate("/");
                console.log('success => ', e)
              }}
              onError={(e) => console.log("Error:", e)}
            />
          </div>
        </div>
      }
      {(isSessionLoading || isUserLoading) && <p>Loading...</p>}
    </Fragment>
  );
};

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:

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.

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.

Was this helpful?

Self-Service SSO Configuration

SSO Configuration Example