Passkey Authentication with Client SDKs

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.

Client SDK

Install SDK

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.
• persistTokens: Controls whether session tokens are stored in browser localStorage. Enabled by default and accessible via getToken(). Set to false to avoid client-side storage of tokens to reduce XSS risk.
• sessionTokenViaCookie: Controls whether the session token is stored in a cookie instead of localStorage. If persistTokens is true, then by default, the token is stored in localStorage. Set this to true to store the token in a JS cookie instead.
• storeLastAuthenticatedUser: Determines if the last authenticated user's info is saved in localStorage. Enabled by default and accessible via getUser(). Set to false to disable this behavior.
• keepLastAuthenticatedUserAfterLogout: Controls whether user info is kept after logout. Disabled by default. Set to true to store user data on logout.

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"
          persistTokens={true} // set to `false` to disable token storage in browser to prevent XSS
          sessionTokenViaCookie={false} // set to `true` to store the session token in a JS cookie instead of localStorage
          storeLastAuthenticatedUser={true} // set to `false` to disable storing last user
          keepLastAuthenticatedUserAfterLogout={false} // set to `true` to persist user info after logout
        >
        <App />
      </AuthProvider>
	);
};

OIDC Configuration

If you're using our SDK as an OIDC client with our Federated Apps, you can initialize the oidcConfig parameter with the following items:

• applicationId: This is the application id, that can be found within the settings of your Federated Application
• redirectUri: This is the url that will be redirected to if the user is unauthenticated. The default redirect URI will be used if not provided.
• scope: This is a string of the scopes that the OIDC client will request from Descope. This should be one string value with spaces in between each scope. The default scopes are: 'openid email roles descope.custom_claims offline_access'

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.

// 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)
}

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.

// Args:
//    loginId: email or phone - must be same as provided at the time of signup.
const loginId = "xxxxx"
 
const descopeSdk = useDescope();
let resp = await descopeSdk.webauthn.signIn(loginId)
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)
}

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.

// 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)
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)
}

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.

// 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)
}

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.