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:
-
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
-
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 JWTrefreshJwt
.
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 successfuly 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.
- Extract the unique code (<unique-code > ) from the URL parameter.
- 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
.