Appkey Biometric Authentication

Early Access

Appkeys can be integrated in TrustX using a biometric-bound, solution where the authentication is tied to the User's biometric such as face or fingerprint that was used to register the Appkey.

This document will describe how to configure a Process Definition and flow that will integrate Appkeys using a biometric-bound authentication solution.

For this process, the integrating application will implement the Appkey Javascript Library to handle biometric capture. This document will describe the steps required to integrate this library in your application before configuring the flow in the Process Designer.

Integrating Trust and FIDO SDKs

To successfully capture biometrics (face and fingerprint) for Appkey registration and authentication, integration with the Trust and FIDO SDKs is required.

See the integration guides below for further steps before continuing to create a biometric authentication flow.

1. Trust SDK Integration

2. FIDO SDK Integration

Configuring the TrustX Appkey Web SDK

The Daon Appkey Javascript library provides secure biometric registration and authentication capabilities for web and mobile environments. It offers a simple JavaScript API for implementing user registration and authentication workflows that can be integrated with TrustX API.

The Appkey Web SDK can be installed using NPM:

JSON
Copy

For Android applications, if you are using Typescript, it is also required to add the following:

Typescript
Copy

Usage Example:

Typescript
Copy

A full explanation of the SDK can be found in the TrustX Appkey Web SDK guide.

See the Appkey Web SDK API Reference guide for a full API reference.

Configuring the Registration Policy

Before creating a Process Definition, it is important to define the Appkey Registration Policy. This is where the type of key to register can be defined:

  • Device - The Appkey will be device bound.
  • Biometric - The Appkey will be bound to a biometric of the end-user.
  • Device and Biometric - The Appkey will be both device and biometric bound.

To create a new Appkey Policy, follow the steps outlined below.

  1. Navigate to Identity Stores > Policies in the Backoffice application.
  2. Select an Identity Store from which the Appkey Policy will be applied.
  3. Click the 'New Appkey Configuration' button to create a new Appkey policy.
  1. The example in this document will use a Biometric bound policy:

For information on the various configuration options available, see the Managing Policies guide.

Configuring the Authentication Policy

Before creating a Process Definition, it is important to define the Appkey Authentication Policy. This is where the type of key to register can be defined:

  • Device - The Appkey will be device bound.
  • Biometric - The Appkey will be bound to a biometric of the end-user.
  • Device and Biometric - The Appkey will be both device and biometric bound.

To create a new Appkey Policy, follow the steps outlined below.

  1. Navigate to Identity Stores > Policies in the Backoffice application.
  2. Select an Identity Store from which the Appkey Policy will be applied.
  3. Click the 'New Appkey Configuration' button to create a new Appkey policy.
  1. The example in this document will use a Device bound policy:

For information on the various configuration options available, see the Managing Policies guide.

Authenticating via Process Definition

The example Process Definition in this guide will utilize a Custom Data Form to handle the authentication of an app key. This process can also be completed using a Custom Page.

Step 1 - Create a Process Definition

  1. Create a new Process Definition by navigating to Process Definitions > New Process Definition in the Backoffice application.
  2. Add a 'Create Start Event' to the Process Designer.
  1. Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
  2. Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.
  1. Click the 'End' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.

Step 2 - Detect User Agent Capabilities

To determine whether Appkeys is supported for the current device, the 'Detect User Agent Capabilities' activity can be used. This activity will retrieve information about the device currently used by the end-user.

  1. Add the 'Detect User Agent Capabilities' activity to the Process Designer and connect it to the 'Start' event using the 'Global connect tool'.
  2. Connect the 'Timer Boundary Event' to the 'End' event.
  1. In the Process Designer, add a 'Custom Data Form v3' activity and connect it to the 'Detect User Agent Capabilities'.

Step 3 - Start Appkey Authentication

The 'Start Appkey Authentication' activity will begin the Appkey authentication process.

  1. Add the 'Start Appkey Authentication' activity to the Process Designer and connect it to the 'Detect User Agent Capabilities' activity using the 'Global connect tool'.
  1. The 'Start Appkey Authentication' activity contains 10 input parameters defined accordingly:
Input ParameterTypeDescription
Appkey Authentication KeyStringRequired - The unique ID associated with the appkey authentication activity.
ChallengeStringThe signed challenge is represented by a public key registered to the User. This value is auto-generated.
Authentication PolicyStringRequired - The name of the authentication policy.
Relying Party IDStringRequired - The ID of the relying party whose appkey authentication configuration will be used.
Server DataStringThis field can contain optional session data that a relying party can associate with the request.
Store NameStringRequired - The name of the Identity Store.
Transaction TextStringA human-readable description of a transaction that is displayed to the user during the transaction confirmation process.
User External IDString

Required - If the 'Create User' property is enabled, this property must be configured as a unique ID for the newly created User.

Optional - If the 'Create User' property is disabled, this property can be used to identify the User that the appkey authentication applies to.

User IDStringThe unique ID automatically generated when the User is created. In the context of the 'Start Appkey Authentication' activity, this ID can be used to identify the User that the appkey authentication applies to.
User KeyStringThe User Key that can be used to identify the User that the appkey authentication applies to.

Step 4 - Prepare the Custom Page

  1. Create a new Custom Page under the Integration Hub > Custom Pages section of the Backoffice.
  2. Click the 'New Custom Page'
  3. Below is an example Custom Page.
index.html
app.js
style.css
Copy
  1. Once the Custom Page has been created, add a 'Custom Page V3' activity to the Process Definition and connect it to the 'Start Appkey Authentication' activity.
  1. Click the 'Custom Page V3' activity to open the right-side contextual menu and expand the 'Session Data' input parameter.
  2. Add the following map entry:
    1. Key: appkeyAuthClientRequest
    2. Value: ${_identityStore.appkeys.authentications["appkeyAuth2"].currentAppkeyAuthenticationRecord.startAppkeyAuthenticationResponse.clientRequestMessage}

Step 5 - Complete Appkey Authentication

The 'Complete Appkey Authentication' activity is used to finalize the appkey authentication process.

  1. Add the 'Complete Appkey Authentication' activity after the 'Custom Page V3' activity and connect using a sequence flow arrow.
  1. The 'Complete Appkey Authentication' activity has the following configurable input parameters:
Input ParameterTypeDescription
Appkey Authentication Browser ResponseString

In order to complete the appkey authentication, a response from the browser must be provided. This response is returned from the Custom Page and can be entered into the 'Appkey Authentication Browser Response' using variable substitution.

${_customUis.{{customPageKey}}_.currentCapture.customPageParameters.appkey.value}

Appkey Authentication KeyStringThe unique ID associated with the Appkey authentication attempt.
Fail Check On CancelBooleanIf enabled, checks will fail if the end-user cancels out of the process. Default behavior is disabled.
  1. The Activity also contains the following error navigation events:
    1. No Appkey On Server: No Appkey was detected on the TrustX server.
    2. No Appkey On Client: No Appkey was detected on the client device.
    3. Failed Complete Appkey Authentication: The Appkey authentication failed to complete.
    4. User Canceled: The user manually cancelled out of the flow.

Test Appkey Authentication

Test Authentication Flow

This section will demonstrate a simple Appkey biometric authentication and how to view the results of the Process Instance and device information captured during the Process Instance.

To begin testing, create a new Process Token by following the steps below.

  1. From the Backoffice application, navigate to Process Definitions > Process Tokens.
  2. Click the 'New Process Token' button on the Process Tokens landing page.
  3. Choose the Process Definition and version then click the 'Create Token' button
  4. Access the URL or scan the QR code to begin the flow.
  5. When reaching the TrustWeb flow, the Custom Page requesting an identifier will appear. Enter a unique ID and click the 'Continue' button to complete the process.

View Results

To view the results of the completed Process Instance, navigate to the Process Instances page in the Backoffice application.

  1. Navigate to the Process Instances page and search for the Process Instance completed as part of the appkey authentication.
  2. From the individual Process Instance page, details about the appkey authentication can be found listed under the 'Checks' section as 'appkeyAuthentication'.
  1. The Client Response retrieved from the Custom Page can be viewed under the 'Custom Pages' section.
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard