OIDC Authentication with WebJS SDK
Install the SDK
Install the Descope WebJS SDK using your preferred package manager:
npm install @descope/web-js-sdkyarn add @descope/web-js-sdkpnpm add @descope/web-js-sdkbun install @descope/web-js-sdkInitialize 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).
import { DescopeSdk } from '@descope/web-js-sdk';
const sdk = DescopeSdk({
projectId: '__ProjectID__',
persistTokens: true,
autoRefresh: true
});Start OIDC Login
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
login_hint: 'user@example.com', // Optional: pre-fill the form.externalId context key
});
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 theform.externalIdcontext 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:
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:
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:
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);
}
}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.
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.