Face Authentication

Early Access

Introduction

TrustX Offers identity verification through biometric face authentication. An Identity Store User with an associated face image can be authenticated against a live captured face image to verify the identity of the end-user.

This guide will describe the steps required to:

1. Capture an image and add the face to an Identity Store User.
2. Capture a second image and perform face match authentication.
3. Manually lock a User if the number of match attempts exceeds the configured limit.

Completing Face Authentication

This example flow demonstrates:

1. Creating a new User in an identity store
2. Enrolling a face to that User
3. Capture a User’s face
4. Match the captured face against the enrolled face

Typically face enrollment and matching will be two separate flows. This document performs both in one flow as an example.

Step 1 - Add a User (Optional)

This step is only required if the User has not been added to the Identity Store. See Managing Users for more information on adding a User.

1. The 'Add User' activity is used to add a new User to an Identity Store. Find the activity and connect it to the 'Start' and 'End' events using a sequence flow arrow.

2. The 'Add User' activity includes two error events. In this example, the error events have been connected to the 'End' event.

   1. Failed to add the user - This event is triggered when an error occurs adding the User to the Identity Store.
   2. ExtId Not Unique - This event occurs if the External ID provided is not unique.

3. Click the 'Add User' activity to open the right-side contextual menu. Using the available input parameters, information about the User can be defined, including the External ID and which Identity Store the user will be added to.

4. When creating a User, the following input parameters are available:

Step 2 - Configure the Face Capture Process

1. Add a 'Capture Face Image' or 'Capture Face Image V2' activity to capture a face image.
2. Perform a face quality assessment using a 'Face Quality Assessment' activity.
3. Connect the activities using sequence flow arrows. In this example, a 'Simple Decider' activity has also been added.

4. When starting the Process Instance, the end-user will be prompted to capture a face image:

Step 3 - Add Face Image to User Activity

The 'Add Face Image to User' activity stores a face image against a user and transforms the image into one or more face biometric templates which are mathematical representations of the image which are stored with the user and are used when performing a face match.

1. Add the 'Add Face Image to User' activity and connect them using a sequence flow arrow.

2. Click the 'Add Face Image to User' activity to open the right-side contextual menu to configure the input parameters.

3. It is important to configure each of the following parameters to ensure the correct face image, User, and Identity Store are used.

When defining which User the the face image will be added to, only one of the User ID input parameters is required.

Add Face Image to User Via API

Alternatively, a face image can be added to a User via the TrustX API.

Endpoints:

• /api/identity-store/stores/{storeName}/users/{userExtId}/biometrics/ext
• /api/identity-store/{tenantId}/stores/{storeName}/users/{userId}/biometrics

This query can be used to add or update an existing face biometric associated with a User.

Permissions: TNT#{tenant}#IdentityStore:addUserBiometricByExtId , TNT#{tenant}#IdentityStore:addUserBiometric

Example Request:

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storename}/users/{userId}/biometrics

Content-Type: application/json

Authorization: Bearer {{token}}

​

{

  "type": "Face",

  "subtype": "Image",

  "data": "/9j/4AAQSkZJRgABAQAAAAAAAAD/4QBMRXhpZgAATU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAABAAEAAKACAS..."

}

Step 4 - Capture a Second Face Image

In this step, the face capture process from Step 2 is repeated to capture a face that will be used to compare against the User face image.

To distinguish between the first captured face image, the face key must be set within the input parameters. In this example, the second face key is set to face2:

Step 5 - Perform Face Match Authentication

The 'Match Face Image to User' activity matches a User’s enrolled face against a captured face.

The face image to be matched must have previously been captured using an existing TrustX activity as shown in the example flow and is referenced by a face key, for example face2 in this example to distinguish it from the enrolled face, face1. The Identity Store and User against whom the matching will take place must be set.

The User may be referenced either by the user ID or external ID depending on the scenario. The updated User will be stored and referenced by the provided Identity Store user key which defaults to user1. The maximum number of attempts defaults to 3 after which a boundary event is triggered as shown in the example process definition diagram below.

1. Add the 'Match Face Image to User' activity to the Process Designer and connect after the second 'Face Quality Assessment' is completed.

2. The 'Match Face Image to User' has the following configurable input parameters:

3. When verification is completed, the end-user will receive confirmation from TrustWeb.

Perform Face Match Via API

It is also possible to perform a Face Match via the TrustX API by using the /api/identity-store/stores/{storeName}/users/{userId}/biometrics/authentications/face endpoint.

A face match sample must be provided with a type of Face, a subtype of Image or a supported template type, the data set to the image or template data and a status, typically set to ACTIVE.

If the storeAudit configuration field is set to true in the identity store's biometric authentication configuration then a detailed audit of the biometric authentication is created.

Permissions: TNT#{tenant}#IdentityStore:matchFace

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storename}/users/{userId}/biometrics/authentications/face

Content-Type: application/json

Authorization: Bearer {{token}}

​

{

  "sample":{  

  "type": "Face",

  "subtype": "Image",

  "status": "ACTIVE",

    "data": "/9j/4AAQSkZJRgABAQAAAQABAAD//gA7Q1JFQVRPUjogZ2..."

  }

}

Step 6 - Error Handling and Locking

Locking configuration is configured on an Identity Store which can define how many failed authentications results in a temporary or permanent user lock. Every time a face authentication fails the User lock status is updated as dictated by the configuration. For more information on locking via Identity Store configuration, see the Managing Identity Stores guide.

It is also possible to hard lock and unlock a User during a process using the 'Lock User' and Unlock User' activities.

1. Add a 'Lock User' activity to the Process Designer and connect it to the 'Exceed face match to user count' error boundary event. This will lock the User if the max attempts count is exceeded.

2. In the example configuration above, the User will become locked if the count of failed face matches is exceeded. Finally, the flow will end. The 'Lock User' activity contains the following input parameters: