OIDC Authentication with WebJS SDK

Install the SDK

Install the Descope WebJS SDK using your preferred package manager:

Terminal

npm install @descope/web-js-sdk

Initialize the SDK

Initialize the Descope SDK with your project ID. You can find this ID on the project page of your Descope console.

Note

You can also add the optional baseUrl parameter if you're utilizing a custom domain within your Descope project (ex: https://auth.company.com).

main.js

import { DescopeSdk } from '@descope/web-js-sdk';
 
const sdk = DescopeSdk({
  projectId: '__ProjectID__',
  persistTokens: true,
  autoRefresh: true
});

Use sdk.oidc.loginWithRedirect() to initiate the OIDC login process:

async function startOIDCLogin() {
  const resp = await sdk.oidc.loginWithRedirect({
    redirect_uri: window.location.origin // Optional: defaults to current URL
  });
  
  if (!resp.ok) {
    console.log("Failed to start OIDC flow")
    console.log("Status Code: " + resp.code)
    console.log("Error Code: " + resp.error.errorCode)
  } else {
    console.log("Successfully Started OIDC flow")
    window.location.replace(resp.data.url)
  }
}

`loginWithRedirect` Parameters

You can pass any of the following parameters into the loginWithRedirect function to provide additional info to the OIDC provider:

redirect_uri: A custom URI that overrides the default redirect after login. This will default to being the current URL.
login_hint: A hint to Descope of the user identifier (e.g., email address). This will pre-fill the form.externalId context key in the flow you're redirected to.

Handle the OIDC Redirect

After successful authentication, the user is redirected back to your application. Call sdk.finishLoginIfNeeded() to complete the process:

redirect.js

async function handleOIDCRedirect() {
  try {
    // This will automatically take the OIDC query params from the current URL and finish the login process
    await sdk.finishLoginIfNeeded();
    console.log("Successfully finished OIDC flow")
    // Redirect to authenticated area
  } catch (error) {
    console.error('Failed to finish OIDC login:', error);
  }
}

Maintain Session

To ensure the session persists across your application, add this to all authenticated pages:

session.js

async function checkSession() {
  try {
    await sdk.refresh();
    const sessionToken = sdk.getSessionToken();
    if (!sessionToken || sdk.isJwtExpired(sessionToken)) {
      // Redirect to login
      window.location.href = '/login';
    }
  } catch (error) {
    console.error('Session check failed:', error);
  }
}

Logout

To log out the user, you can use either local logout or OIDC-compliant logout:

logout.js

async function handleLogout() {
  try {
    // Local logout
    await sdk.logout();
    // OR OIDC-compliant logout
    await sdk.oidc.logout();
    
    window.location.href = '/';
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

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.

Congratulations

Now that you've got the authentication down, go focus on building out the rest of your app!

Checkpoint

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

Need help?

Customize

Was this helpful?