SSO Configuration Flow

Descope allows you to embed a widget-like version of the SSO Setup Suite within your application. The SSO config flow is embedded like other Descope flows and allows your tenants' administrators to configure their own SAML/OIDC external IdPs with Descope. This allows your B2B customers to configure their SSO without directly interacting with you as the application administrator.

SSO Configuration Flow Example

The video below will walk you through the experience of configuring an IdP using the Self-Service Configuration feature.

Self-Service SSO Configuration Example using Mock SAML

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

• Descope
• Okta
• Auth0
• CyberArk
• PingFederate
• PingOne
• DUO
• JumpCloud
• Salesforce
• OneLogin
• Entra ID (Azure AD)
• Google Workspace
• miniOrange
• Classlink
• LastPass

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
• SCIM Provisioning
• Test SAML/OIDC SSO provider login on demand

Embedding the SSO Config Flow

Similarly to Descope widgets and post auth flows, you can embed the SSO configuration widget within your application. Users must be authenticated with the SSO Admin permission to interact with the SSO config flow.

Below are examples of embedding the flow using our SDKs; these examples also show how to validate that the user has the SSO Admin permission before displaying the flow.

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 embed the self-service SSO configuration widget, the user you want to utilize it must have the SSO Admin permission.

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. Once you choose the IdP, the flow will walk the user through the entire end-to-end application configuration within the IdP and prompt the user for the configurations needed for the Descope tenant.

User / Group Attribute Mapping

Next, you must ensure that all the proper user and group attributes are mapped accordingly in Descope. User attributes are mapped based on the claim name configured and sent from the external IdP.

Group mappings from the IdP can be mapped to 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 before having the tenant admins run through this configuration widget.

Configuring SSO Domains

The final step is to configure the tenant's SSO company domain. This domain, 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 completed the SSO configuration setup process, you'll be taken to a screen that allows you to change various configurations in the future. If you wish to test the SSO connection you configured, click the Test button. This will redirect you to the proper IdP and allow you to sign in. When you return, you'll see the SAML assertion, along with any errors related 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.

Below is an example of the response within the test page.

SCIM Provisioning

You can also configure SCIM provisioning via the flow while configuring the SSO configuration. Once on the SCIM provisioning screen within the flow, click Generate SCIM Token to create the tenant's applicable access key.

Once the access key is created, copy it and the SCIM provisioning URL from the flow into your SCIM configuration within the IdP.

For more information on SCIM provisioning, visit our SCIM Management Guide.