---
title: Authentication
description: "\"Shows how to authenticate (sign-on) a new user by comparing their current facial biometrics with the ones saved during PingOne Recognize enrollment.\""
component: recognize
page_id: recognize:web-sdk:web-sdk-guide-authentication
canonical_url: https://docs.pingidentity.com/recognize/web-sdk/web-sdk-guide-authentication.html
llms_txt: https://docs.pingidentity.com/recognize/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
section_ids:
  before-you-begin: Before you begin
  headless-integration: Headless integration
  web-component-integration: Web component integration
---

# Authentication

Authentication is the biometric equivalent of signing-on. PingOne Recognize compares the user's current facial biometrics with the ones saved during [enrollment](web-sdk-guide-enrollment.html).

If the biometrics match, PingOne Recognize authenticates the user.

## Before you begin

Make sure you have met the [prerequisite requirements](web-sdk-prerequisites.html) before continuing.

## Headless integration

The `@keyless/sdk-web` library lets you integrate the PingOne Recognize Web SDK without using UI controls. Here's an authentication example:

> **Collapse: Details**
>
> ```javascript
> import {
>   addKeylessEventListeners,
>   createKeylessAuth,
>   createKeylessMediaStream,
>   getKeylessCameraPermissionState,
>   getKeylessVideoMediaDevices,
>   getLastKeylessServerFrameTriggeredBiometricFilters,
>   getLastKeylessVideoFrameQuality,
>   importKeylessWebAssemblyModuleOrThrow,
>   isKeylessVideoMediaStreamAvailable,
>   KeylessError,
>   openKeylessWebSocketConnection,
>   reduceKeylessBiometricFiltersToTriggered,
>   removeKeylessEventListeners
> } from '@keyless/sdk-web'
>
> function requestTransactionJwtVerification(jwt) {}
> function requestUserCameraPermission() {}
>
> function handleCameraOperativityError(error) {}
> function handleImportKeylessWebAssemblyModuleError(error) {}
> function handleCreateKeylessMediaStreamError(error) {}
> function handleOpenKeylessWebSocketConnectionError(error) {}
>
> /**
>  * This event is fired when an error occurs during the authentication process.
>  * The error object contains a `message` property that indicates the type of error.
>  */
> function onKeylessError(sym, error) {
>   /**
>    * Removing event listeners is advised on terminal events since
>    * no more than one attempt is allowed per authentication symbol.
>    */
>   removeKeylessEventListeners(sym)
>
>   // will log the error code
>   console.error(error.message)
> }
>
> /**
>  * This event is fired when the authentication process is complete.
>  * It does not fire for failed attempts, only successful ones.
>  */
> function onKeylessFinished(sym, message) {
>   /**
>    * Removing event listeners is advised on terminal events since
>    * no more than one attempt is allowed per authentication symbol.
>    */
>   removeKeylessEventListeners(sym)
>
>   /**
>    * The `transactionJwt` is a JSON Web Token (JWT) that contains information
>    * about the authentication transaction.
>    *
>    * This token is signed by the Keyless Authentication Service and can be used
>    * to verify the authenticity of the transaction.
>    *
>    * This operation is strictly backend-to-backend and should never be performed
>    * in client-side code.
>    */
>   requestTransactionJwtVerification(message.transactionJwt)
> }
>
> /**
>  * This event is useful for providing real-time feedback to users during
>  * the authentication process, such as prompting them to adjust their position
>  * or lighting conditions to improve biometric recognition.
>  *
>  * The difference with "onKeylessVideoFrameQuality" is that this is from
>  * filters running on the server.
>  */
> function onKeylessFrameResults(sym, message) {
>   let filters
>
>   /**
>    * Returns an array of biometric filters that were triggered in the last frame.
>    * If no biometric filters were triggered, an empty array is returned.
>    */
>   filters = reduceKeylessBiometricFiltersToTriggered(message.filters)
>
>   /**
>    * Optionally, this function can be used to retrieve the filters that were triggered
>    * in the last frame.
>    *
>    * This can be useful if you need to access the last frame's triggered filters outside
>    * of the frame results event.
>    *
>    * If this function is used then this event is useful for requesting an update to the UI.
>    */
>   filters = getLastKeylessServerFrameTriggeredBiometricFilters(sym)}
>
> /**
>  * This event is useful for providing real-time feedback to users during
>  * the authentication process, such as prompting them to adjust their position
>  * or lighting conditions to improve biometric recognition.
>  *
>  * The difference with "onKeylessFrameResults" is that this is from filters
>  * running on the client.
>  */
> function onKeylessVideoFrameQuality(sym, event) {
>   /**
>    * Will log an array of filters that were triggered in this frame.
>    * If no biometric filters were triggered, an empty array is returned.
>    */
>   console.log(event.filters)
>
>   /**
>    * Optionally, this function can be used to retrieve the quality of the last
>    * video frame.
>    *
>    * This can be useful if you need to access the last video frame quality outside
>    * of the video frame quality event.
>    *
>    * If this function is used then this event is useful for requesting an update to the UI.
>    */
>   console.log(getLastKeylessVideoFrameQuality(sym))
> }
>
> async function ensureCameraOperativity() {
>   let devices, state
>
>   devices = await getKeylessVideoMediaDevices()
>
>   /**
>    * If the error is MEDIA_DEVICES_NO_VIDEO_INPUTS, it means that
>    * the user does not have any camera available.
>    */
>   if (devices instanceof Error && devices.message === KeylessError.MEDIA_DEVICES_NO_VIDEO_INPUTS) throw devices
>
>   state = await getKeylessCameraPermissionState()
>
>   /**
>    * If the camera permission state is not 'granted', request
>    * the user's device doesn't have a camera.
>    */
>   if (state !== 'granted') {
>     /**
>      * Ideally this function should take the user to a UI prompt
>      * where they can grant camera access to the website.
>      *
>      * The easiest way to trigger the browser's camera permission prompt
>      * is to call isKeylessVideoMediaStreamAvailable(), which will return
>      * a boolean indicating whether the user granted camera access or not.
>      */
>     requestUserCameraPermission()
>     throw new Error('camera permission state is not granted')
>   }
>
>   devices = await getKeylessVideoMediaDevices()
>
>   /**
>    * If the error is MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL, it means that
>    * even though the user has granted camera access, the browser requires
>    * the user to start a video stream to be able to read the camera labels.
>    *
>    * In this case, we perform a throwaway getUserMedia() request with
>    * isKeylessVideoMediaStreamAvailable() to start a video stream
>    * to be able to read the camera labels.
>    */
>   if (devices instanceof Error && devices.message === KeylessError.MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL) {
>     let available
>
>     available = await isKeylessVideoMediaStreamAvailable()
>     if (!available) throw new Error('video media stream is not available')
>
>     devices = await getKeylessVideoMediaDevices()
>   }
>
>   /**
>    * If we still have an error, throw an error to indicate that
>    * the media devices still could not be read correctly.
>    */
>   if (devices instanceof Error) throw devices
> }
>
> async function authenticateWithKeyless() {
>   let auth, options, stream, open
>
>   /**
>    * Create a Keyless authentication symbol.
>    *
>    * This symbol must be kept in memory for the duration of the authentication process.
>    * To perform multiple authentications, a new symbol must be created for each authentication.
>    */
>   auth = createKeylessAuth()
>
>   /**
>    * Add event listeners through the Keyless authentication symbol.
>    * These listeners will handle events during the authentication process.
>    */
>   addKeylessEventListeners(auth, [
>     { name: 'error', callback: (error) => onKeylessError(auth, error) },
>     { name: 'finished', callback: (message) => onKeylessFinished(auth, message) },
>     { name: 'frame-results', callback: (message) => onKeylessFrameResults(auth, message) },
>     { name: 'video-frame-quality', callback: (event) => onKeylessVideoFrameQuality(auth, event) }
>   ])
>
>   options = {
>     authorization: {
>       token: 'USER_AUTHORIZATION_FROM_CUSTOMER'
>     },
>     customer: { name: 'CUSTOMER_NAME' },
>     key: { id: 'IMAGE_ENCRYPTION_KEY_ID', value: 'IMAGE_ENCRYPTION_PUBLIC_KEY' },
>     transaction: {
>       data: 'DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
>     },
>     username: 'USERNAME',
>     ws: { url: 'KEYLESS_AUTHENTICATION_SERVICE_URL' }
>   }
>
>   /**
>    * Create a media stream from the user's video input media device.
>    * This stream will be used to capture video frames for biometric analysis.
>    *
>    * Note: The user must grant permission to access the media device.
>    */
>   stream = await createKeylessMediaStream()
>   if (stream instanceof Error) return handleCreateKeylessMediaStreamError(stream)
>
>   /**
>    * Open a WebSocket connection to the Keyless Authentication Service.
>    * This connection will be used to process video frames and receive authentication results.
>    */
>   open = await openKeylessWebSocketConnection(auth, options)
>   if (open instanceof Error) return handleOpenKeylessWebSocketConnectionError(open)
> }
>
> importKeylessWebAssemblyModuleOrThrow()
>   .then(() =>
>     ensureCameraOperativity()
>       .then(() => authenticateWithKeyless())
>       .catch(handleCameraOperativityError)
>   )
>   .catch(handleImportKeylessWebAssemblyModuleError)
> ```

## Web component integration

This section shows how to use HTML to authenticate.

* React

* Vue

* Embedded

```javascript
import '@keyless/sdk-web-components'

export function KeylessAuth() {
  onError = (event) => {
    // will log the error code
    console.log(event.message)
  }

  onFinished = (event) => {
    /**
     * The `transactionJwt` is a JSON Web Token (JWT) that contains information
     * about the authentication transaction.
     *
     * This token is signed by the Keyless Authentication Service and can be used
     * to verify the authenticity of the transaction.
     *
     * This operation is strictly backend-to-backend and should never be performed
     * in client-side code.
     */
    requestTransactionJwtVerification(message.transactionJwt)
  }

  return (
    <kl-auth
      authorization-token='USER_AUTHORIZATION_FROM_CUSTOMER'
      customer='CUSTOMER_NAME'
      enable-camera-instructions
      key-id='IMAGE_ENCRYPTION_KEY_ID'
      lang='en'
      onerror={onError}
      onfinished={onFinished}
      public-key='IMAGE_ENCRYPTION_PUBLIC_KEY'
      size='375'
      theme='light'
      transaction-data='DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
      username='USERNAME'
      ws-url='KEYLESS_AUTHENTICATION_SERVICE_URL'
    />
  )
}
```

```javascript
<script setup>
import '@keyless/sdk-web-components'

function onError(event) {
  // will log the error code
  console.log(event.message)
}

function onFinished(event) {
  /**
   * The `transactionJwt` is a JSON Web Token (JWT) that contains information
   * about the authentication transaction.
   *
   * This token is signed by the Keyless Authentication Service and can be used
   * to verify the authenticity of the transaction.
   *
   * This operation is strictly backend-to-backend and should never be performed
   * in client-side code.
   */
  requestTransactionJwtVerification(message.transactionJwt)
}
</script>

<template>
  <kl-auth
    customer="CUSTOMER_NAME"
    enable-camera-instructions
    @error="onError"
    @finished="onFinished"
    key="IMAGE_ENCRYPTION_PUBLIC_KEY"
    key-id="IMAGE_ENCRYPTION_KEY_ID"
    lang="en"
    size="375"
    theme="light"
    transaction-data='DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
    username="USERNAME"
    ws-url="KEYLESS_AUTHENTICATION_SERVICE_URL"
  />
</template>
```

```javascript
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Auth</title>
    <style>
      * {
        box-sizing: border-box;
      }

      body {
        align-items: center;
        display: flex;
        justify-content: center;
        margin: 0;
        min-height: 100vh;
        padding: 8px;
      }

      kl-auth {
        border: 1px solid lightgray;
      }
    </style>
  </head>
  <body>
    <kl-auth
      customer="CUSTOMER_NAME"
      enable-camera-instructions
      key="IMAGE_ENCRYPTION_PUBLIC_KEY"
      key-id="IMAGE_ENCRYPTION_KEY_ID"
      lang="en"
      size="375"
      theme="light"
      transaction-data='DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
      username="USERNAME"
      ws-url="KEYLESS_AUTHENTICATION_SERVICE_URL"
    ></kl-auth>
    <script src="./node_modules/@keyless/sdk-web-components/index.js" type="module"></script>
    <script>
      const auth = document.querySelector('kl-auth')

      auth.addEventListener('error', (event) => {
        // will log the error code
        console.log(event.message)
      })

      auth.addEventListener('finished', (event) => {
        /**
         * The `transactionJwt` is a JSON Web Token (JWT) that contains information
         * about the authentication transaction.
         *
         * This token is signed by the Keyless Authentication Service and can be used
         * to verify the authenticity of the transaction.
         *
         * This operation is strictly backend-to-backend and should never be performed
         * in client-side code.
         */
        requestTransactionJwtVerification(message.transactionJwt)
      })
    </script>
  </body>
</html>
```