Authentication

Authentication is the biometric equivalent of "signing-in". During authentication Keyless compares the user's facial biometrics with the ones computed during enrollment.

If the biometrics match, Keyless authenticates the user.

Headless Integration

The @keyless/sdk-web library lets you integrate the Keyless Web SDK however you want in terms of UI/UX, let's see a basic example of authentication:

import { KeylessAuth } from '@keyless/sdk-web'

const auth = new KeylessAuth()

// in order to perform an authentication you need to pass a liveness check,
// this means that you need to have multiple natural different frames of the face,
// they should be captured from a live camera feed like a webcam
const frames = ['base16-frame-1', 'base16-frame-2', '...']

auth.on('begin-image-stream', async () => {
  await auth.sendImageStream(frames[0])
  
  // remove used frame
  frames.shift()
})

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

auth.on('image-accepted', () => {
  if (frames.length <= 0) {
    throw new Error('No more frames')
  }
  
  // some time needs to pass between one frame and the other,
  // this is handled gracefully in our web components by having a framerate of 4fps
  setTimeout(async () => {
    await auth.sendImageStream(frames[0])
    
    // remove used frame
    frames.shift()
  }, 200)
})

auth.on('finished-authentication', (event) => {
  // if the result was 'FAILURE' it means that face recognition failed
  if (event.data.authenticationResult === 'FAILURE') {
    throw new Error('recognition failed')
  }
  
  // if the result was 'SUCCESS' it means that the user authenticated
  if (event.data.authenticationResult === 'SUCCESS') {
    return console.log('authentication successful')
  }
  
  // if result is missing or does not equal either 'FAILURE' or 'SUCCESS'
  // it's an anomaly or bug, so handle it as 'FAILURE'
  throw new Error('authentication failed')
})

await auth.connect({
  key: { id: 'IMAGE_ENCRYPTION_KEY_ID', value: 'IMAGE_ENCRYPTION_PUBLIC_KEY' },
  username: 'USERNAME',
  ws: { url: 'KEYLESS_AUTHENTICATION_SERVICE_URL' }
})

In this example we handle all the necessary events to perform an authentication with a continous stream of face frames, and if it fails the error code will be logged to the console.

Web Component Integration

Previously we have explained how to perform authentication in a headless way with the @keyless/sdk-web package, now we'll provide an example of doing so with raw HTML syntax.

<!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
      enable-camera-instructions
      key="IMAGE_ENCRYPTION_PUBLIC_KEY"
      key-id="IMAGE_ENCRYPTION_KEY_ID"
      lang="en"
      size="375"
      theme="light"
      username="USERNAME"
      ws-url="KEYLESS_AUTHENTICATION_SERVICE_URL"
    ></kl-auth>
    <script src="@keyless/sdk-web-components/elements/auth/auth-element.iife.js"></script>
    <script>
      const auth = document.querySelector('kl-auth')
      
      auth.addEventListener('error', (event) => {
        // will log error code
        console.log(event.message)
      })

      auth.addEventListener('finished', (event) => {
        // if the result was 'FAILURE' it means that face recognition failed
        if (event.detail.result === 'FAILURE') {
          throw new Error('recognition failed')
        }
        
        // if the result was 'SUCCESS' it means that the user authenticated
        if (event.detail.result === 'SUCCESS') {
          return console.log('authentication successful')
        }
        
        // if result is missing or does not equal either 'FAILURE' or 'SUCCESS'
        // it's an anomaly or bug, so handle it as 'FAILURE'
        throw new Error('authentication failed')
      })
    </script>
  </body>
</html>

That's it, everything is handled by the @keyless/sdk-web-components package, especially the more complex parts of capturing camera frames and sending them at a proper framerate to the Authentication Service.

Last updated