Biometrics Authentication

This authentication guide is meant for developers that are NOT using Descope to design login screens and authentication flows. If you’d like to use Descope Flows, Quick Start should be your starting point.

Introduction

WebAuthn lets you authenticate end users using the strong authenticators that are now often built right into devices, including biometrics (fingerprint, facial, or iris recognition) and secure hardware keys (for example, Yubico, CryptoTrust, or Thedis). These secure hardware keys, also known as passkeys, can be USB tokens or embedded security features in smartphones or computers. A typical method for implementing WebAuthn has two sets of functionality to program: user onboarding and session validation.

App Client to Descope Integration

Install SDK

ReactNextJSNextAuthWebJSVue.jsHTMLAngular

npm i --save @descope/react-sdk

npm i --save @descope/next-sdk

npm i --save next-auth

npm i --save @descope/web-js-sdk

npm i --save @descope/vue-sdk

<!-- Not applicable for HTML -->

npm i --save @descope/angular-sdk

Import and initialize SDK

ReactNextJSNextAuthWebJSVue.jsHTMLAngular

import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'

const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			// If the Descope project manages the token response in cookies,
            // a custom domain must be configured
            // (e.g., https://auth.app.example.com)
			// and should be set as the baseUrl property.
			// baseUrl = "https://auth.app.example.com"
		>
			<App />
		</AuthProvider>
	);
};

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<AuthProvider projectId="__ProjectID__">
			<html lang="en">
				<body>{children}</body>
			</html>
		</AuthProvider>
	);
}

// app/api/auth/[...nextauth]
import { NextAuthOptions } from "next-auth"
import NextAuth from "next-auth/next";

export const authOptions: NextAuthOptions = {
  providers: [
    {
      id: "descope",
      name: "Descope",
      type: "oauth",
      wellKnown: `https://api.descope.com/${process.env.DESCOPE_PROJECT_ID}/.well-known/openid-configuration`,
      authorization: { params: { scope: "openid email profile" } },
      idToken: true,
      clientId: process.env.DESCOPE_PROJECT_ID,
      clientSecret: process.env.DESCOPE_ACCESS_KEY,
      checks: ["pkce", "state"],
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
          image: profile.picture,
        }
      },
    },
  ], 
  callbacks: {
    async jwt({token, account, profile}) {
      if (account) {
        return {
          ...token,
          access_token: account.access_token,
          expires_at: Math.floor(Date.now() / 1000 + account.expires_in),
          refresh_token: account.refresh_token,
          profile: {
            name: profile?.name,
            email: profile?.email,
            image: profile?.picture,
            },
          }
        } else if (Date.now() < token.expires_at * 1000) {
          return token
        } else {
          try {
            const response = await fetch("https://api.descope.com/oauth2/v1/token", {
              headers: {"Content-Type": "application/x-www-form-urlencoded"},
              body: new URLSearchParams({
                client_id: "__ProjectID__",
                client_secret: "<Descope Access Key>",
                grant_type: "refresh_token",
                refresh_token: token.refresh_token,
              }),
              method: "POST",
            })
            
            const tokens = await response.json()
            
            if (!response.ok) throw tokens
            
            return {
              ...token,
              access_token: tokens.access_token,
              expires_at: Math.floor(Date.now() / 1000 + tokens.expires_in),
              refresh_token: tokens.refresh_token ?? token.refresh_token,
            }
          } catch (error) {
            console.error("Error refreshing access token", error)
            return {...token, error: "RefreshAccessTokenError"}
            }
          }
        },
    
        async session({session, token}) {
          if (token.profile) {
            session.user = token.profile;
          }
    
          session.error = token.error
          session.accessToken = token.access_token
          return session
        },
    }
}

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

// app/provider.tsx
'use client'

import { SessionProvider } from "next-auth/react"


export default function NextAuthSessionProvider(
    { children }:
    { children: React.ReactNode }
) {
    return (
        <SessionProvider>
            { children }
        </SessionProvider>
    )
}

// app/layout.tsx
import NextAuthSessionProvider from './provider'


export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NextAuthSessionProvider>
          <div>
            {children}
          </div>
        </NextAuthSessionProvider>
      </body>
    </html>
  )
}

import DescopeSdk from '@descope/web-js-sdk';
try {
    //  baseUrl="<URL>" // you can also configure the baseUrl ex: https://auth.company.com - this is useful when you utilize CNAME within your Descope project.
    const descopeSdk = DescopeSdk({ projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

import { createApp } from "vue";
import App from "@/App.vue";
import descope, { getSdk } from "@descope/vue-sdk";

const app = createApp(App);
app.use(router);

app.use(descope, {
  projectId: '__Project_ID__',
  baseUrl: "<base url>", // Optional
});

const sdk = getSdk();
sdk?.onSessionTokenChange((newSession) => {
  // here you can implement custom logic when the session is changing
});

<head>
    <script src="https://unpkg.com/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
    <!-- Please replace `x.x.x` with the latest version of the WebJS SDK, which you can get from [here](https://www.npmjs.com/package/@descope/web-js-sdk) -->
</head>

// app.module.ts
import { NgModule, APP_INITIALIZER} from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { DescopeAuthModule, DescopeAuthService, descopeInterceptor } from '@descope/angular-sdk';
import { AppComponent } from './app.component';
import {
	HttpClientModule,
	provideHttpClient,
	withInterceptors
} from '@angular/common/http';
import { zip } from 'rxjs';

export function initializeApp(authService: DescopeAuthService) {
	return () => zip([authService.refreshSession(), authService.refreshUser()]);
}

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    DescopeAuthModule.forRoot({
      projectId: 'YOUR_PROJECT_ID'
    })
  ],
  providers: [
    {
        provide: APP_INITIALIZER,
        useFactory: initializeApp,
        deps: [DescopeAuthService],
        multi: true
      },
      provideHttpClient(withInterceptors([descopeInterceptor]))
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

User Sign-Up

The first step for implementing WebAuthn authentication is Sign-Up. Within the web-js-sdk, the Sign-Up function is one call to the Descope Service. This defers from the backend SDKs which require a start call and stop call for each of the tasks covered here, as the backend must push the information to the browser and receive further information back from the browser. The new end user will be registered after the full WebAuthn flow has been completed. The below sample code demonstrates how to implement WebAuthn Sign-Up within your client application.

ReactWebJSHTML

// Args:
//    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
const loginId = "xxxxx"
//    name: User's name. Ex: firstName lastName
const name = "Joe Persons"

const descopeSdk = useDescope();
let resp = await descopeSdk.webauthn.signUp(loginId,name)
if (resp.ok != true) {
  console.log("Failed to complete WebAuthn sign-up")
  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 completed WebAuthn sign-up")
  console.log(resp)
}

// Args:
//    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
const loginId = "xxxxx"
//    name: User's name. Ex: firstName lastName
const name = "Joe Persons"

let resp = await descopeSdk.webauthn.signUp(loginId,name)
if (resp.ok != true) {
  console.log("Failed to complete WebAuthn sign-up")
  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 completed WebAuthn sign-up")
  console.log(resp)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function webauthnSignUp() {
    // Args:
    //    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
    const loginId = document.getElementById("loginId").value
    //    name: User's name. Ex: firstName lastName
    const name = document.getElementById("name").value

    const resp = await descopeSdk.webauthn.signUp(loginId, name);
    if (!resp.ok) {
      window.alert("Failed to sign up via Biometrics (Webauthn) \nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully signed up via Biometrics (Webauthn) ")
      window.location.replace("../loggedIn.html?userId=" + encodeURIComponent(loginId) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

User Sign-In

For signing in with an existing user via WebAuthn, you will utilize the signIn function. Within the web-js-sdk, the Sign-In function is one call. This defers from the backend SDKs which require a start call and stop call for each of the tasks covered here, as the backend must push the information to the browser and receive further information back. Upon successful verification of the Sign-In, the user will be logged in and the response will include the JWT information. The below sample code demonstrates how to implement WebAuthn Sign-In within your client application.

ReactWebJSHTML

// Args:
//    loginId: email or phone - must be same as provided at the time of signup.
const loginId = "xxxxx"
//    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();
let resp = await descopeSdk.webauthn.signIn(loginId, loginOptions)
if (resp.ok != true) {
  console.log("Failed to sign-in via WebAuthn")
  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 signed in via WebAuthn")
  console.log(resp)
}

// Args:
//    loginId: email or phone - must be same as provided at the time of signup.
const loginId = "xxxxx"
//    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

let resp = await descopeSdk.webauthn.signIn(loginId, loginOptions)
if (resp.ok != true) {
  console.log("Failed to sign-in via WebAuthn")
  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 signed in via WebAuthn")
  console.log(resp)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function webauthnSignIn() {
    // Args:
    //    loginId: email or phone
    const loginId = document.getElementById("loginId").value
    //    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 descopeSdk.webauthn.signIn(loginId, loginOptions);
    if (!resp.ok) {
      window.alert("Failed to login via Biometrics (Webauthn) \nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully logged in via Biometrics (Webauthn) ")
      window.location.replace("../loggedIn.html?userId=" + encodeURIComponent(loginId) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

User Sign-Up or In

Within the web-js-sdk, the Sign-Up Or In function is one call to the Descope Service. This defers from the backend SDKs which require a start call and stop call for each of the tasks covered here, as the backend must push the information to the browser and receive further information back from the browser. The new end user will be registered after the full WebAuthn flow has been completed. The below sample code demonstrates how to implement WebAuthn Sign-Up or in within your client application.

ReactWebJSHTML

// Args:
//    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
const loginId = "xxxxx"
//    name: User's name. Ex: firstName lastName
const name = "Joe Persons"

const descopeSdk = useDescope();
let resp = await descopeSdk.webauthn.signUpOrIn(loginId,name)
if (resp.ok != true) {
  console.log("Failed to complete WebAuthn sign-up or in")
  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 completed WebAuthn sign-up or in")
  console.log(resp)
}

// Args:
//    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
const loginId = "xxxxx"
//    name: User's name. Ex: firstName lastName
const name = "Joe Persons"

let resp = await descopeSdk.webauthn.signUpOrIn(loginId,name)
if (resp.ok != true) {
  console.log("Failed to complete WebAuthn sign-up or in")
  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 completed WebAuthn sign-up or in")
  console.log(resp)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function signUpOrIn() {
    // Args:
    //    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
    const loginId = document.getElementById("loginId").value
    //    name: User's name. Ex: firstName lastName
    const name = document.getElementById("name").value

    const resp = await descopeSdk.webauthn.signUpOrIn(loginId, name);
    if (!resp.ok) {
      window.alert("Failed to sign up or in via Biometrics (Webauthn) \nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully signed up or in via Biometrics (Webauthn) ")
      window.location.replace("../loggedIn.html?userId=" + encodeURIComponent(loginId) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

Add User Device

The update function within the web-js-sdk adds a new biometric signature or a device to an existing user account. You should use this function in scenarios where a user has already authenticated (signup complete) with your service via another method. This function requires a valid refresh token from another authentication method. Within the web-js-sdk, the update function is one call. This defers from the backend SDKs which require a start call and stop call for each of the tasks covered here, as the backend must push the information to the browser and receive further information back. The below sample code demonstrates how to implement WebAuthn update within your client application.

ReactWebJSHTML

// Args:
//    loginId: email or phone - must be same as provided at the time of signup.
const loginId = "xxxxx"
//     token: a refresh token for the user you are wanting to add a device for
const token = "xxxxxx"

const descopeSdk = useDescope();
let resp = await descopeSdk.webauthn.update(loginId, token)
if (resp.ok != true) {
  console.log("Failed to add device via WebAuthn")
  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 added device via via WebAuthn")
  console.log(resp)
}

// Args:
//    loginId: email or phone - must be same as provided at the time of signup.
const loginId = "xxxxx"
//     token: a refresh token for the user you are wanting to add a device for
const token = "xxxxxx"

let resp = await descopeSdk.webauthn.update(loginId, token)
if (resp.ok != true) {
  console.log("Failed to add device via WebAuthn")
  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 added device via via WebAuthn")
  console.log(resp)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function webauthnAddDevice() {
    // Args:
    //    loginId: email or phone - becomes the externalID for the user from here on and also used for delivery
    const loginId = document.getElementById("loginId").value
    //     token: a refresh token for the user you are wanting to add a device for
    const token = document.getElementById("refreshToken").value

    const resp = await descopeSdk.webauthn.update(loginId, token);
    if (!resp.ok) {
      window.alert("Failed to add device via Biometrics (Webauthn) \nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully added device via Biometrics (Webauthn) ")
      window.alert("Successfully added device via Biometrics (Webauthn), please login via biometrics from the loaded screen after closing this alert.")
      window.location.replace("./signInWithWebauthn")
    }
  }
</script>

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.

Application is working Need Help?

Was this article helpful?Yes No