Appkey Device Authentication

Early Access

Appkeys can be integrated in TrustX using a silent, device-bound, solution where the authentication is tied to the device used to register the Appkey. This solution means end-users will not be required to register any biometric and binds the authentication to only one device.

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

Integrating Trust and FIDO SDKs

The most secure method of storing Appkeys is to store the Appkey on a device by integrating a native application with the Trust AND FIDO SDKs. Alternatively, Appkeys will be stored via the web browser, however this method is less secure.

Daon recommends integrating the Trust and FIDO SDKs first before continuing with the steps outlined in this guide.

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

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

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.

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

Integration Method 1

The integration method described in this section provides a customizable solution using a Custom Page to invoke the Appkey capabilities in the browser, passing in the request from TrustX and sending the response to TrustX.

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

2. The 'Start Appkey Authentication' activity contains 10 input parameters defined accordingly:

(Optional) Start Appkey Authentication via API

The Appkey authentication process can be started via the API by calling either:

• /api/identity-store/stores/{storeName}/users/{userId}/appkeys/relyingParties/{rpId}/authentications/{authPolicyName}
• /api/identity-store/{tenantId}/stores/{storeName}/users/{userExtId}/appkeys/relyingParties/{rpId}/authentications/{authPolicyName}/ext.

Permissions: TNT#{tenant}#IdentityStore:createAppkeyAuthenticationForUser, TNT#{tenant}#IdentityStore:createAppkeyAuthenticationForUserByExtId , TNT#{tenant}#IdentityStore:createAppkeyAuthentication

Example Request:

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storename}/users/{userID}/passkeys/relyingParties/{rpId}/authentications/{authPolicyName}

Content-Type: application/json

Authorization: Bearer {{token}}

​

{

​

}

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.

<!doctype html>

<html lang="en">

  <head>

    <meta charset="UTF-8" />

    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>Vite + React + TS</title>

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

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

  </head>

  <body>

    <div id="root"></div>

  </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 Authentication' activity.

5. Click the 'Custom Page V3' activity to open the right-side contextual menu and expand the 'Session Data' input parameter.
6. 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.

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

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

(Optional) Complete Appkey Authentication via API

The appkey authentication process can be started via the API by calling either:

• /api/identity-store/stores/{storeName}/users/{userId}/appkeys/relyingParties/{rpId}/authentications/{authPolicyName}
• /api/identity-store/{tenantId}/stores/{storeName}/users/{userExtId}/appkeys/relyingParties/{rpId}/authentications/{authPolicyName}/ext

Permissions: TNT#{tenant}#IdentityStore:createAppkeyAuthenticationForUser, TNT#{tenant}#IdentityStore:createAppkeyAuthenticationForUserByExtId , TNT#{tenant}#IdentityStore:createAppkeyAuthentication

Example Request:

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{storename}/users/{userID}/passkeys/authentications/sessions/{sessionId}

Content-Type: application/json

Authorization: Bearer {{token}}

​

{

}

Integration Method 2

The 'Appkey Authentication' activity provides a quick out-of-the-box solution to Appkey authentication compared to the method discussed in Integration Method 1.

The method described in this section will demonstrate how to configure a Process Definition to use this activity.

Step 3 - Appkey Authentication

1. After the 'Detect User Agent Capabilities', add an 'Appkey Authentication' activity to the flow and connect them using the 'Global connect tool'.

2. The 'Appkey Authentication' activity contains the following input parameters:

Test Appkey Authentication

Test Authentication Flow

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

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