SSO Migration

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.

This creates a totally seamless user login experience for your end users with pre-configured IdPs, without forcing your tenant administrators to have to re-configure their SAML/OIDC settings on their end at all. In this article, we will cover all of the steps required to eventually migrate your customer tenants to Descope.

Solution Overview

The following chart demonstrates your current implementation for Single-Sign-On:

And this chart, demonstrates the implementation, post migration:

1. When the end user starts the SSO authentication, a Descope relay state will be created.
2. Once the user is redirected to the IdP, authentication happens as usual.
3. Once the authentication is complete, the IdP response returns to the same SP ACS URL the customer had set previously in the IdP's settings.
4. Using a DNS provider, the response will be redirected to Descope, passing all the needed parameters to complete the authentication.
5. Descope will handle the final response and authenticate the user.
6. The user will be authenticated and logged in.

Prerequisites

• A Descope project with Descope API/SDK access.
• A custom domain set up.
• A DNS provider.

Setup Process

Setup overview:

1. Implementing SSO authentication with Descope Flows / SDK
2. Setting up the Descope tenants with the SSO settings
3. Setting Up the DNS redirect
4. Testing the Integration
5. Moving Forward With Descope

Implementing SSO authentication with Descope Flows / SDK.

First, SSO with Descope should be implemented in the application.

• Authenticate with SSO Using Flows.
• Authenticate with SSO Using SDK - client side, server-side or mobile.

Not sure? Follow this guide to get a general perspective on the implementation.

To ensure a smooth migration, with the ability to "A/B test" and rollback in case things go wrong, the authentication with Descope should be set up with a specific and customized logic that will ensure only specific tenants (customers) will use Descope. Here is a simple example (using React):

function login (tenant) {
 
    if (migrationTenants.includes(tenant)) {
        <div>
        <Descope flowId='<flow-id>'
        tenant
        >
        </Descope>
      </div>
    } else {
      // old SP logic
    }
}

Setting up the Descope tenants with the SSO settings

After making sure that the authentication works, set up the customer tenants.

Set up a Descope tenant for each migrating customer. Follow the instructions below to match the required protocol.

SAML

1. Create the tenants.

• Using the UI
• Using the API
• Using the SDK

2. Acquire the settings from the previous identity provider. These settings are tenant (customer) specific and should match the same values your customer had provided for the previous provider.

To allow Descope to accept and communicate with the customer's IdP, the default Descope 'EntityId' and 'ACS URL' need to be changed.

These values, referred to commonly below as spEntityId and spAcsUrl, should correspond to what is already set in the customer's IdP.

Use the API or SDK to set the following values:

curl -X POST "https://api.descope.com/v1/mgmt/sso/saml" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ProjectId:ManagementKey>" \
  -d '{
  "tenantId": "xxxxx",
  "settings": {
    ...
    "spACSUrl": "https://mydomain.com/saml",
    "spEntityId": "my-custom-entityid"
  },
  "domains": [
    "mydomain.com"
  ]
}'

3. Verify the settings by viewing the created tenants -> Select the tenant -> Authetication Methods -> SSO. Or by using the API.

OIDC

1. Create the tenants.

• Using the UI
• Using the API
• Using the SDK

2. Acquire the settings from the previous identity provider. These settings are tenant (customer) specific and should match the same values your customer had provided for the previous provider.

3. Set up the SSO OIDC settings, by following this guide.

4. Verify the settings by viewing the created tenants -> Select the tenant -> Authetication Methods -> SSO. Or by using the API.

Setting Up the DNS Redirect

After creating the customer tenants, set up the DNS redirect.

CloudFlare

Using CloudFlare as the DNS provider, a "Worker" is needed to process and redirect the requests using custom logic.

Follow these instructions to create and deploy a new Cloudflare Worker to handle the redirect.

• Go to https://dash.cloudflare.com/

• Create an Account level token:

  • Manage Account > Account API Tokens > Create token > "Edit Cloudflare Workers"

• Copy the created token and export it as an environment variable locally:

export CLOUDFLARE_API_TOKEN=<CLOUDFLARE_TOKEN>

• Clone the worker template, from our official template from here.

• Update wrangler.toml

  • Line 27 - set your old backend host (old-auth.example.com).
  • Lines 14-15 to your pattern and zone.

• Run and deploy:

npm i && npm run deploy

Testing the Integration

After completing the migration steps, test the integration with your own tenants or test accounts.

Moving Forward With Descope

Migration works? here are details on what's next.

Once migration is set, it will serve your customer as long as the same values are used or valid. For reasons like a pro-active change of settings or expiry of a certificate, perform a seamless migration to Descope with the Tenant Self Service Provisioning. For home-grown implementations, read our documentation about Tenant Management to update the settings accordingly.

Eventually, the users should be able to seamlessly sign in with their respective IdPs, without having to force the administrators to change any settings on their end.