SSO (Single Sign-On) APIs

Use the SSO (Single Sign-On) APIs to let end users sign-in to all authorized using the same credentials.

Overview

Implementing SSO using the APIs is a two step process:

1. Sign-In - Call the Start SSO endpoint to authenticate your end user. After the end user has successfully signed-in you will get a unique code, which will be exchanged for a user object in the next step. Access authorization to a specific service provider application can be managed in any of the following ways:
   • (recommended) Map and manage end user access using Descope roles and groups for a specific tenant
   • Manage access manually using the roles and access mechanism provided by each individual service provider
2. Exchange Code - call the Exchange SSO Code endpoint which will exchange the unique code for a user object, which includes the session JWT sessionJwt and refresh JWT refreshJwt.

Implementing SSO

Sign-in

Call the Start SSO endpoint to authorize your end user to sign-in. Descope will walk the end user through the SSO sign-in process. The endpoint takes two arguments:

• tenant - specific tenant for which to sign-in the end user
• redirectURL - destination URL you want the end user session to be redirected to after successfully signing in

The API response returns url, which is theredirectURL with a unique code (<unique-code\>) appended as a URL parameter. For example, if redirectURL = https://sso.mycompany.com/mywork.htm then url = https://sso.mycompany.com/mywork.htm?code=<unique-code\>.

After the end user has been successfully authenticated with the identity provider (IdP) the end user session is redirected to url.

Exchange Code

In your source code that responds to user session being redirected to url, exchange the unique code (<unique-code\>) from the URL parameter for a Descope user object.

1. Extract the unique code (<unique-code\>) from the URL parameter.
2. Call the Exchange SSO Code endpoint.

The endpoint response will return a valid User Object, which includes the session JWT sessionJwt and refresh JWT refreshJwt.