SSO Setup Suite

When it comes to configuring SSO with your B2B customers, Descope understands that the configuration can be complex and iterative when manually working with customers to configure their IDP. To resolve these struggles, Descope has developed the SSO Setup Suite. The SSO Setup Suite enables your customers to be self-sufficient in configuring their IdP to work with your application.

Descope's SSO Setup Suite walks your customers through the entire process, including:

Configuration of the IdP.
User attribute and group mappings.
Testing the configuration allows them to view the assertion and validate the configuration.
Configure SCIM provisioning.

Initiating the SSO Setup Suite

You can generate the SSO Setup Suite link for your user in a few ways.

Manual Generation of SSO Configuration Link

On your tenant's configuration page in the Descope console, click the Generate Link button to generate a link you can share with your customer's administrator to walk through the SSO configuration.

Once the link has been generated, you can copy it from the Descope UI or enter the recipient's email and send it.

Note

Once you have configured your custom CNAME, the URL generated will have your custom CNAME (ex: auth.example.com) rather than api.descope.com.

Automated Generation of SSO Configuration Link

You'll most commonly want to generate and share an SSO Suite Link programmatically with your B2B customer's administrator via Descope Flows, API, or SDK. The sections below outline ways to automate sending the link to your users.

Generate the SSO Setup Suite Link via Descope API

You can use the API to generate and send the SSO Configuration Link.

Generate the SSO Setup Suite Link via Descope SDK

You can use the Descope management SDK to generate and send the SSO configuration link as well.

// Args:
//	tenantId: the tenant ID to generate the link for
const tenantId = "T2..."
//	expireDuration: The expiration parameter takes a number to add in milliseconds to the current time.
const expireDuration = 10000000
//	ssoId (optional): If provided, it indicates which SSO Profile within the tenant to configure for the SSO Setup Suite Link. 
//	email  (optional): If provided, the link will also be emailed to the recipient.
//	templateId (optional): If provided, this template will be used to email the user.
 
const link = await descopeClient.management.tenant.generateSSOConfigurationLink(tenantId, expireDuration);

Generate SSO Setup Suite Link via Descope Flows

You can use the Generate SSO setup suite admin link action in a flow when you're creating a tenant and building your onboarding flow. Once you have generated the link via the action, you can use the dynamic key of {{adminLinks.ssoConfiguration}} within a link within a flow screen or send it to a user via an email or SMS connector.

Below is an example flow that checks if the user is a new user to the tenant, gives the user the tenant admin permission, and generates the link.

Revoking the SSO Setup Suite Link

If you manually revoke/expire the SSO Setup Suite Link, you can do so from within the tenant's configuration page in the Descope console by clicking the Revoke Link button.

You can also revoke the SSO Setup Suite Link via the Descope API.

Using the SSO Setup Suite

SSO Configuration

Once you have given the SSO Setup Suite link to your B2B customer's administrator, they can start configuring their SSO IdP by clicking the SSO configuration button.

Identity Provider (IdP) Selection

Once you have started the configuration process, you'll see the screen for selecting the IdP. The user can choose from the list of available IdP configuration guides; note that the list of supported providers can be expanded by selecting Show More, or the user can manually configure SAML 2.0 or OIDC from the options below.

Note

If the user chooses one of the supported providers that supports either SAML or OIDC, there will be button options to select which one.

Service Provider Information

Once the user has selected a provider, the guide will populate and walk the user through configuring their SAML/OIDC provider. This guide includes the tenant-specific data that needs to be copied into the company's IdP settings.

User Attribute Mapping

Once the user has started configuring the application, the user will walk through the next section to configure User Attribute Mapping. This is the area where you can configure the data prepopulated to the user, such as: email, name, and groups.

Note

You can only configure existing user attributes or groups within the Descope project. You can create custom user attributes or roles to allow your customers to map to.

Identity Provider Information

The Identity Provider Information section is where the user provides the IdP information for the Descope tenant. This would be the metadata URL or various configurations, such as the SSO URL, Entity ID, and certificate.

Assign Users and Groups

You will be prompted to add user and group assignments within the IdP application when you visit the assign users and groups section of the SSO Setup Suite.

SSO Domains

Within the SSO domains step, the user can 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

Once the user has configured their IdP, they can test the configuration on the testing page. This will redirect you to the newly configured IdP and allow you to sign in. When you return, you'll see the SAML assertion and 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.