Appkey Biometric Registration

Early Access

Appkeys can be integrated in TrustX using a biometric-bound, solution where the registration is tied to the User's biometric such as face or fingerprint.

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

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 registration flow.

1. Trust SDK Integration

• Android Trust SDK Integration
• iOS Trust SDK Integration

2. FIDO SDK Integration

• Integrating the FIDO SDK with TrustX

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:

// package.json

"dependencies": {

    ...

    "@daon/trustx-appkey": "file:./path/to/DaonAppkey-{version}.tgz"

}

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

// index.d.ts

declare module '@daon/trustx-appkey';

Usage Example:

import { registration, authentication } from '@daon/trustx-appkey';

​

// Registration

const payload = await registration({ appkeyRegClientRequest, language, translations });

​

// Authentication

const payload = await authentication({ appkeyAuthClientRequest, language, translations, transactionCallback });

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.

4. The example in this document will use a Biometric bound policy:

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

Registering via Process Definition

The example Process Definition in this guide will utilize a Custom Data Form to handle the registration 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.

3. Click the 'Start' event to open the right-side contextual menu and enter a name for the 'Name' input parameter.
4. Add a 'Create End Event' to the Process Designer and connect it to the 'Start' event using a sequence flow arrow.

5. 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.

Step 3 - Create User External ID Form

To request an External ID from the end-user, a Custom Data Form can be used. This section will describe how to set up a Custom Data Form that accepts user input and pass it to a Cloud Function for processing.

1. To create a Custom Data Form, navigate to the Integration Hub > Custom Forms section of the Backoffice application.
2. Click the 'New Custom Form' button located at the top-right of the Custom Forms landing page.
3. An example JSON form can be found below. This form will request a string as input that requires an identifier to be entered.

{

    "title": {

        "values": {

            "en": "Enter your identifier"

        },

        "isValid": true,

        "type": "title"

    },

    "components": [

        {

            "type": "text",

            "isValid": true,

            "readOnly": false,

            "id": "userExtId",

            "label": {

                "values": {

                    "en": "Identifier"

                }

            },

            "default": "",

            "transient": false,

            "validate": {

                "required": true,

                "minLength": "",

                "maxLength": "",

                "missingMessage": {

                    "values": {

                        "en": ""

                    }

                },

                "invalidMessage": {

                    "values": {

                        "en": ""

                    }

                },

                "invalidLengthMessage": {

                    "values": {

                        "en": ""

                    }

                }

            },

            "index": 0

        }

    ]

}

4. In the Process Designer, add a 'Custom Data Form v3' activity and connect it to the 'Detect User Agent Capabilities'.

Step 4 - Process Custom Form with a Cloud Function

1. Create a new Cloud Function but navigating to the Cloud Functions page in the Backoffice application.
2. Click the 'New Cloud Function' button on the Cloud Functions landing page to create a new Cloud Function.

import json

from cfresults import Outcome, Result, OverallResult, OverallResultEncoder

​

overallResult = OverallResult(Outcome.APPROVE, {})

cfResults = json.loads(OverallResultEncoder().encode(overallResult))

results["cfResults"] = cfResults

​

userExtIdCdfMap = params["vars"].get("_customFormData", {}).get("UserExtIdCdf", {}).get("currentCapture", {}).get("customDataFormDataMap", {})

userEnteredExtId = userExtIdCdfMap.get("userExtId")

​

​

pvars = {

    "userEnteredExtId": userEnteredExtId

}

results["executionVariables"] = pvars

3. From the Process Definition, add an 'Execute Cloud Function v2' activity and connect it to the 'Custom Data Form v4' activity.

Step 5 - 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 'Execute Cloud Function v2' activity.

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 6 - Start Appkey Registration

The 'Start Appkey Registration' activity will begin the Appkey registration process.

1. Add the 'Start Appkey Registration' activity to the Process Designer and connect it to the 'Add User' activity using the 'Global connect tool'.

2. The 'Start Appkey Registration' activity contains 11 input parameters defined accordingly:

Step 7 - 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.

<!DOCTYPE html>

<html lang="en">

<head>

  <meta charset="UTF-8">

  <title>Appkey Demo</title>

  <link rel="stylesheet" href="style.css" />

</head>

<body>

  <form id="registration">

    <h1>Register with Appkey's</h1>

  </form>

​

  <script type="module" src="app.js"></script>

  <script src="DaonAppkey.v1.0.13.min.js"></script>

</body>

</html>

4. Once the Custom Page has been created, add a 'Custom Page V3' activity to the Process Definition and connect it to the 'Start Appkey Registration' activity.

Step 8 - Complete Appkey Registration

The 'Complete Appkey Registration' activity is used to finalize the appkey registration process.

1. Add the 'Complete Appkey Registration' activity after the 'Custom Page V3' activity and connect using a sequence flow arrow.

2. The 'Complete Appkey Registration' activity has the following configurable input parameters:

Test Appkey Registration

Test Authentication Flow

This section will demonstrate a simple appkey biometric registration 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 'appkeyRegistration'.

3. The Client Response retrieved from the Custom Page can be viewed under the 'Custom Pages' section.