SSO (Single Sign-On) APIs

Use the SSO (Single Sign-On) APIs to let end users sign in to all authorized applications 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. On success, you receive a unique code to exchange for a user object in the next step. Access authorization to a specific service provider application can be managed in either 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 to 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 authenticate your end user. Descope walks the end user through the SSO sign-in process. The endpoint takes two arguments:

• tenant — the specific tenant for which to sign in the end user
• redirectURL — destination URL the end user session is redirected to after successfully signing in

The API response returns url, which is the redirectURL 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 the 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 returns a valid User Object, which includes the session JWT sessionJwt and refresh JWT refreshJwt.