OAuth Social Login Guide | Backend SDK

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 many social logins such as Google, Facebook, Microsoft, etc. You can find the currently supported list of social logins in the Descope console at Settings>Authentication Methods>Social Login (OAuth). The Descope console has the defaults set for all social logins. You can customize these by configuring the social logins with your company account.

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope client, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize a custom domain within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Start OAuth

The first step in OAuth is to start the oauth process with the Identity Provider of your choice such as Google, Facebook, Microsoft etc. For this step you need call oauth start function from your app client after user clicks on social login icon.

// Args:
//   provider: social identity provider for authenticating the user. Supported values include "facebook", "github", "google", "microsoft", "gitlab" and "apple". The current list can be found at https://github.com/descope/core-js-sdk/blob/main/src/sdk/oauth/types.ts in the OAuthProviders array.
const provider = "facebook"
//   redirect_url: URL to return to after successful authentication with the social 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 redirect_url = "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 resp = await descopeClient.oauth.start[provider](redirect_url, loginOptions);
if (!resp.ok) {
  console.log("Failed to start oauth")
  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 provider_url = resp.data.url
  console.log("Successfully started oauth. URL: " + provider_url)
}

Finish OAuth (Exchange Token)

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

// Args:
//   code: code extracted from the url after user is redirected to redirect_url. The code is in the url as a query parameter "code" of the page.
const code = "xxxxx"
 
const response = await descopeClient.oauth.exchange(code);
if (!resp.ok) {
  console.log("Failed to finish oauth")
  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 finished oauth.")
  console.log(resp)
}

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 backend 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?

Social Login (OAuth) with Backend SDKs