Android Trust SDK Integration Guide

Introduction

This guide is aimed at developers and will provide the necessary steps for integrating with the Trust SDK. The guide offers a step by step walkthrough on how to authenticate with TrustX and start a TrustX authentication or Identity Verification process through the Trust SDK.

To complete this guide, the reader must have access to the TrustX back office application in order to create API Keys and Process definitions. If the reader does not have access to the TrustX back office application, they can request access via support@daon.com

Add the Trust SDK to your Gradle Project

To get started with the the Trust SDK, begin by adding the SDK to your Gradle project.

  1. Copy the following AAR files to your module 'libs' folder. If you don't have a 'libs' folder then create one. New projects module 'libs' folder location should be 'My Application/app/libs'.

    1. daon-trust-sdk-1.0.x.aar

  2. Open your module level Gradle settings file. New projects module Gradle settings location should be My Application/app/build.gradle.

  3. Make the ‘libs’ folder easily accessible. To do that, add the following lines to your ‘module’ level Gradle file:

Groovy
Copy

By default, you might not have any settings for repositories in your ‘module’ level ‘build.gradle’ file. If this is the case, you can simply add it to the end of the file outside any other objects. Also, it is possible that you already have flatDir { dirs 'libs' } in your repositories. In this case, no change is necessary. If you are using a newer gradle version, there may be a requirement to add flatDir support to the ‘settings.gradle‘ file. It should be located in the same folder as the project-level ‘build.gradle‘ file. In ‘settings.gradle‘ add following lines:

dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { //Posible some other repositories flatDir { dirs 'libs' } } }
  1. Add libraries for the Daon Trust SDK along with other necessary dependencies to your ‘module’ Gradle dependencies:
Groovy
Copy

TrustX Integration Overview

Sequence Diagram with calls for a typical integration scenario.

Sequence Diagram with calls for a typical integration scenario.

This guide assumes that the user is integrating from a mobile application. In summary:

  • The End User starts the journey on a Relying Party's application, possibly by clicking on a button or a link to start the TrustX Identity Verification and Authentication journey.

  • The Relying Party makes a series of calls to TrustX. These calls serve a number of purposes:

    • Authenticate the relying party so that they can makes calls to TrustX.
    • Create a Process Instance from a Process Definition based on a Process Token.

  • The mobile application has imported the Trust SDK. See Android Trust SDK Native Interface for more information.

  • Start the Process Definition and redirect the End User to TrustX so that the end user can complete the journey.

A Relying Party is a term commonly used to refer to the entity wishing to establish a claim of Identity.

Step 1. Create Token

A Token is created by invoking the API call below:

HTTP
Copy

A token grants access to the caller to invoke API calls on TrustX. Once the token is generated it can be reused, however it must be noted that the token has a 'time to live'. Once the 'time to live' has expired a new token must be generated.

When calling the API to issue a token, you will need to provide an API Key. This API Key is obtained from an API Key's secret. See the API Key Guide for information on how to manage API keys.

When the api/arthr/apiKeys/issue API is invoked, the response to this call provides a bearer token. This bearer token is used to authenticate subsequent calls to TrustX.

The permissions required for the APIs calls within this integration guide are as follows (note: replace {tenantid} with literal value):

Permissions
Copy

Tokens should be protected - they should reside only in the back end service and should not be publicly shared by embedding in web pages. If a token is compromised it can provide bad actors access to your services and data in TrustX.

Step 2. Create Process Token

A process token is used to create process instances from a Process Definition. For more information on creating a Process Definition, see the Process Definition Guide. When creating the process token the process definition name and version must be supplied.

Daon recommends that the _redirectUrl uses the HTTPS protocol.
HTTP
Copy

When creating a process instance, extra parameters can be passed to provide additional information about the process. For example, the End User's details such as email, phone, first-name, surname, etc. can be passed as parameters. See the API Guide for more information.

Process Token Resource

The process token resource above contains the following attributes. See the API Guide for more information.

TypeDescription
namestringA unique name to describe the process token.
descriptionstringA short description of the token
statusstring

The process token status.

In the example above we create the token to be active.

Valid values: ACTIVE,INACTIVE

typestring

The process token status.

In the example above we create the token to be active. Valid values: UNLIMITED, MULTI_USE COUNT_LIMITED,_ MULTI_USE_TIME_LIMITED

maxCountnumber

The number of times the token can be used.

In the example above the token can be used once only.

processDefnNamestring

The process definition name.

Using the combination of process definition name and process definition version a specific process definition is bound to the process token to be used when a process instance created with a token (See Step 3.)

processDefnVersionstring

The process definition version.

Using the combination of process definition name and process definition version a specific process definition is bound to the process token to be used when a process instance created with a token (See Step 3.)

uiUrlstring

The URI of the application to execute the process definition when the process instance is started.

Currently on TruxtX user interfaces are supported.

parametersMap<String,String>

A map of additional parameters can be supplied to provide extra information when the process instance is started.

This additional parameter map could typically contain information such as:

  • firstName
  • lastName
  • email
  • phoneNumber

These are typically attributes that are useful for searching for an ID&V applicant. Any set of additional parameters may be passed in.

In order to set the redirect URL for the end of a process instance - a special parameter should be added to parameters map - _redirectUrl. This parameter is used to redirect the end user back to the relying party.

Step 3. Create Process Instance

Once a Process Token is created, it can be used to create the Process Instance.

HTTP
Copy

The response provides the redirect URL that is then used to start the process definition.

Optional - Set Default Language

It is possible to set the default language by appending the redirect URL with the lang query parameter. This query parameter accepts an ISO language code as input in the format: redirectUrl + "&lang=<ISO language code>"

Example:

https://skyprod.oak.trustx-dev.com/web/trustweb/?pt=7BU2B6IHVVCZWE2PM5JMZW7GUE&lang=it

Step 4. End User completes Journey

The end user will be redirected to TrustX where they can complete the Identity Verification and Authentication journey as defined in the Process Definition.

Step 5. Getting Process Instance Status

Once the user has completed the journey the status of the process instance can be checked.

HTTP
Copy

Alternatively webhooks can be used to get notification about the process instance at any stage in the process definition. For information on webhooks see the Webhooks Guide.

Step 6. Getting End User's provided Data

HTTP
Copy
TypeDescription
processDefnIdString

The id of the process definition.

This is generated when creating the process definition

processInstanceIdStringThe id of the process instance. This is generated when creating the process instance.

Optional: Appkeys Integration

Appkeys utilize the FIDO Universal Authentication Framework (UAF) specification to provide a passwordless solution to registration and authentication where an identity is bound to only one device or biometric profile without the need for passwords or QR codes.

To take full advantage of Appkeys in TrustX, it is necessary to integrate the FIDO SDK with the Trust SDK to

  1. Store Appkeys on a device for stronger security than the web-based alternative.
  2. Capture biometrics (face, fingerprint) to complete biometric-bound registration and authentication flows with Appkeys.

This section will describe the configuration steps to include the SDK with your Android application.

Dependencies

For Android, the xAuth SDK is provided as a Maven repository. To incorporate the xAuth FIDO SDK, add the following dependencies to your build.gradle file.

Groovy
Copy

The AppKeysManager package can be imported by adding com.daon.trustsdk.appkeysManager to your project.

Example:

Kotlin
Copy

Optional: NFC Integration

The Trust SDK supports optional integration of the NFC capture and processing using the TrustNFCManager class.

Step 1. Update Dependencies

To utilize NFC functionality in your project, it is first required to update the Gradle project to include additional dependencies described in the Add the Trust SDK to your Gradle Project section above.

Add the following libraries to your ‘module’ Gradle dependencies:

Groovy
Copy

Step 2. Initialization

The code sample below implements NFC functionality into the standard document and face capture flow. This occurs during initialization detailed in Step 5.

Java
Kotlin
Copy

In the above sample, a new TrustNFCManager is defined and added to the DaonTrustSDK using the addTrustNFCManager(TrustNFCManager) method.

When the flow is started, NFC capture and processing will be included as part of the flow. To start the flow, define Trust SDK options and call the start(Options) method as highlighted in Step 5.

Java
Kotlin
Copy

ProGuard / R8 Configuration

When code shrinking or obfuscation is enabled (minifyEnabled true), some components may be removed or altered by ProGuard / R8, which can lead to runtime failures during NFC passport reading or certificate verification.

To ensure correct behavior, the following ProGuard rules must be added to your application's proguard-rules.pro file.

IDL
Copy

See Also

Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Android Trust SDK Native Interface
On This Page
Android Trust SDK Integration GuideIntroductionAdd the Trust SDK to your Gradle ProjectTrustX Integration OverviewStep 1. Create TokenStep 2. Create Process TokenProcess Token ResourceStep 3. Create Process InstanceStep 4. End User completes JourneyStep 5. Getting Process Instance StatusStep 6. Getting End User's provided DataOptional: Appkeys IntegrationDependenciesOptional: NFC IntegrationStep 1. Update DependenciesStep 2. InitializationProGuard / R8 ConfigurationSee Also