Single Sign On (SSO) with Client SDKs

This guide is meant for developers that are NOT using Descope Flows to design login screens and authentication methods.

If you'd like to use Descope Flows, Quick Start should be your starting point.

Descope supports SSO as one of the authentication methods for your end-users. When using SSO, the SSO configuration can be different for each tenant. Please refer to the article in the manage section for the configuration of SSO for each tenant.

Client SDK

Install SDK

Terminal

npm i --save @descope/react-sdk

Import and initialize SDK

Parameters:

baseUrl: Custom domain that must be configured to manage token response in cookies. This makes sure every request to our service is through your custom domain, preventing accidental domain blockages.
baseStaticUrl: Custom domain to override the base URL that is used to fetch static files.

import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'
 
const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			baseUrl = "https://auth.app.example.com"
		>
			<App />
		</AuthProvider>
	);
};

Start SSO

The first step in SSO is to start the SSO authentication process with the Identity Provider. For this step you need call sso start function from your app client after user clicks on login icon.

// Args:
//   tenant_name_id_or_email: ID of the tenant that the user is authenticating to. The tenant ID is assigned to tenant at the time of creation.
const tenant_name_id_or_email = "xxxx"
//   redirectURL: URL to return to after successful authentication with the SSO identity provider. You need to implement this page to access the token and finish oauth process (token exchange). The token arrives as a query parameter named 'code'.
const redirectURL = "https://auth.company.com/token_exchange"
//    loginOptions (LoginOptions): this allows you to configure behavior during the authentication process.
const loginOptions = {
      "stepup": false,
      "mfa": false,
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }
//    refreshToken (optional): the user's current refresh token in the event of stepup/mfa
 
const descopeSdk = useDescope();
const resp = await descopeSdk.saml.start(tenant_name_id_or_email, redirectURL, loginOptions);
if (!resp.ok) {
  console.log("Failed to start sso auth")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  const url = resp.data.url
  console.log("Successfully started sso auth. URL: " + url)
}
// The following will parse the URL in one line rather than the above error handling: const url = resp.ok && resp.data.url;
// pending release

SSO Exchange Code

After successful authentication with your IdP the user is redirected to the redirectURL that you provide in the sso start function above. Your application should extract the code from the redirectURL and perform token exchange as shown below.

// Args:
//   code: code extracted from the url after user is redirected to redirectURL. The code is in the url as a query parameter "code" of the page.
const code = "xxxxx"
 
const descopeSdk = useDescope();
const resp = await descopeSdk.saml.exchange(code);
if (!resp.ok) {
  console.log("Failed to verify sso code")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully verified sso code.")
}
// pending release

Session Validation

The final step of completing the authentication with Descope is to validate the user session. Descope provides rich session management capabilities, including configurable session timeouts and logout functions. You can find the details and sample code for client session validation here.

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Was this helpful?