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

Overview

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

Step 1. Create Token

A Token is created by invoking the API call below:

POST https://{{tenant}}.{{region}}.trustx.com/api/arthr/apiKeys/issue

Content-Type: application/json

X-API-Key: {{apiKey}}

​

{}

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):

TNT#{tenantid}#ProcessManager:addProcessToken

TNT#{tenantid}#ProcessManager:getProcessInstance

TNT#{tenantid}#UserDataServer:getProcessInstanceUserData

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.

POST https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processTokens

Content-Type: application/json

Authorization: Bearer {{token}}

​

{

    "name": "My Process Token",

    "description": "A token that allows me to start create an instance of my process definition",

    "status": "ACTIVE",

    "type": "MULTI_USE_COUNT_LIMITED",

    "maxCount": 1,

    "processDefnName": "{{processDefnName}}",

    "processDefnVersion": "{{processDefnVersion}}",

    "uiUrl": "https://{{tenant}}.{{region}}.trustx.com/web/trustweb",

    "parameters": {

        "email": "myemail@daon.com",

        "_redirectUrl": "https://www.daon.com"

     }

}

Process Token Resource

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

Step 3. Create Process Instance

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

POST https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processInstances/create?pt={{ptoken}}

Content-Type: application/json

Authorization: Bearer {{token}}

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

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 5. Initializing the Trust SDK

With the URL generated, the Trust SDK can be initialized.

1. Initialize the DaonTrustSDK:

let sdk = TrustSDK(withViewController: self, delegate: self)

2. Daon Trust SDK offers setting a DaonOptions object for customization purposes. You can set your own initialization timeout as well as the URL of the environment that you want to use:

let options = DaonOptions()

options.serverUrl = "https://www.example.com"

options.initializationTimeout = 15

3. Finally, you can start the Onboarding process by calling 'start()' function of the TrustSDK:

sdk.start(withDaonOptions: options)

Step 6. 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 7. Getting Process Instance Status

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

GET https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processInstances/{{processInstanceId}}

Authorization: Bearer {{token}}

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 8. Getting End User's provided Data

GET https://{{tenant}}.{{region}}.trustx.com//api/userdata-server/processDefinitions/{processDefnId}/processInstances/{processInstanceId}/userdata

Authorization: Bearer {{token}}

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 document will describe the configuration steps to include the FIDO SDK with your iOS application.

Dependencies

Add your GitHub account to Xcode and add the xAuth FIDO SDK as a Swift Package.

It is not required to include every FIDO package as currently only the DaonFIDOSDK library is required.

Example:

It is then possible to add the FIDO SDK dependencies to the Trust SDK.

Example:

import DaonTrustAppkeysProcessor

do {

    let appkeysProcessor = try AppkeysProcessor.Builder()

        .enableDebugLogs(false)

        .enableLocationUsage(false)

        .enableSilentBiometricRegistration(false)

        .setBiometricRegistrationReason(“Registration Reason”)

        .setBiometricAuthenticationReason(“Authentication Reason”)

        .build()

    sdk.addAppkeysProcessor(appkeysProcessor)

} catch {

    // Handle builder error

}

Optional: NFC Integration

The Daon Trust SDK Document Processor provides features to perform OCR of MRZ from document images and NFC scanning of passports and other documents.

This section will describe how to add the Document Processor and add the processor to your project.

Step 1. Add the Processor

To add the Document Processor to your project, perform the steps outlined below.

1. Add the following frameworks to your application target under _Frameworks > Libraries > Embedded Content_:

• DaonTrustSDKDocumentProcessor.xcframework`
  • DaonNFCSDK.xcframework`

2. Ensure that once added, the frameworks are marked as 'Embed & Sign'

Additionally, the OpenSSL library should be added via Swift Package Manager.

To install OpenSSL using Swift Package Manager, follow the steps outlined in Apple's Official Documentation using the URL for the OpenSSL repo with the version: 1.1.2300

1. In Xcode, select 'File > Add Packages...'
2. Enter: https://github.com/krzyzanowskim/OpenSSL.git

Alternatively, this can be added in the dependencies of the Package.swift file_:_

dependencies: [

    .package(url: "https://github.com/krzyzanowskim/OpenSSL.git", from: "1.1.2300")

]

Step 2. Configure the Processor

To create a new instance of the Document Processor you must use the ``DocumentProcessor/Builder class which allows you to configure and then build the processor using method chaining. The document processor can then be added to the Trust SDK instance.

import DaonTrustSDKDocumentProcessor

​

...

​

do {

    // OPTIONAL: Add Document Processor to SDK for MRZ OCR and NFC Passport scanning.

    let documentProcessor = try DocumentProcessor.Builder()

                                                 // Call configuration methods, e.g. .setLicense()

                                                 .build()

    // Add the Document Processor to the Trust SDK instance

    sdk.addDocumentProcessor(documentProcessor)

​

} catch {

    // Handle builder error

}

Once configured, the process can be started by performing the following:

sdk.start(withDaonOptions: options)

Optional: Device Integrity Integration

The device-integrity module is an optional add-on to the Daon Trust SDK that collects Device Integrity Signals. Device Integrity Signals are used to collect rich, high-fidelity telemetry from every web and native session. Device signals can be used to uniquely identify visitors and additional device signals (for example, if a device is rooted/ jailbroken) that can be applied for further fraud analysis.

Requirements

The Device Integrity Signal provider is embedded inside DaonTrustSDKDeviceIntegrityProcessor.xcframework via SPM. No separate installation is required.

Quick Start

Installation

1. Open the target's General tab in Xcode.
2. Under Frameworks, Libraries, and Embedded Content, click the plus (+) button.
3. Choose Add Other… → Add Files… and select DaonTrustSDKDeviceIntegrityProcessor.xcframework from the Frameworks/ directory.
4. Set the embed option to Embed & Sign.

Ensure DaonTrustSDK.xcframework is already present in the same section. The Device Integrity Processor framework depends on the core SDK module being linked first.

Integration

Integration requires three lines of code added before TrustSDK.start(withDaonOptions:) is called.

Swift (UIKit)

import DaonTrustSDK

import DaonTrustSDKDeviceIntegrityProcessor

​

class HomeViewController: UIViewController {

​

    func startOnboarding() {

        guard let sdk = TrustSDK(withViewController: self, delegate: self) else { return }

​

        // Register the Device Integrity processor

        let deviceIntegrityProcessor = DeviceIntegrityProcessor()

        sdk.addDeviceIntegrityProcessor(deviceIntegrityProcessor)

​

        let options = DaonOptions()

        options.urlString = "https://your-trustx-server/flow"

        sdk.start(withDaonOptions: options)

    }

}

SwiftUI

import DaonTrustSDK

import DaonTrustSDKDeviceIntegrityProcessor

​

class TrustSDKCoordinator {

​

    func startOnboarding(url: String) {

        let sdk = TrustSDK(withViewController: hostViewController, delegate: self)

​

        let deviceIntegrityProcessor = DeviceIntegrityProcessor()

        sdk.addDeviceIntegrityProcessor(deviceIntegrityProcessor)

​

        let options = DaonOptions()

        options.urlString = url

        sdk.start(withDaonOptions: options)

    }

}

DeviceIntegrityProcessor can be combined with other processors. Registration order does not matter.

sdk.addDocumentProcessor(documentProcessor)    // optional

sdk.addAppkeysProcessor(appkeysProcessor)      // optional

sdk.addDeviceIntegrityProcessor(DeviceIntegrityProcessor())

sdk.start(withDaonOptions: options)

App Clip Builds

DeviceIntegrityProcessor depends on the Device Integrity Signal provider, which adds non-trivial binary size. Exclude it from App Clip targets using a compiler flag:

#if !APPCLIP

import DaonTrustSDKDeviceIntegrityProcessor

#endif

​

func startOnboarding() {

    // ...

    #if !APPCLIP

    sdk.addDeviceIntegrityProcessor(DeviceIntegrityProcessor())

    #endif

    sdk.start(withDaonOptions: options)

}

Set the APPCLIP Swift Active Compilation Condition on your App Clip target under Build Settings → Swift Compiler — Custom Flags → Active Compilation Conditions. When the processor is not registered the Device Integrity module is simply absent from the capabilities response, and the server skips the device integrity step for that session.

Error Handling

Errors from the Device Integrity Processor are surfaced through the standard DaonEventDelegate callbacks — no additional error handling is required in the application. When a fingerprint operation fails, the SDK reports the failure back to the web layer and the server determines how to proceed with the onboarding flow.

API Reference

DeviceIntegrityProcessor conforms to the DaonDeviceIntegrityProcessorModule protocol defined in DaonTrustSDK .

Privacy

DaonTrustSDKDeviceIntegrityProcessor.xcframework declares:

• NSPrivacyTracking: false — the framework itself does not perform tracking.
• NSPrivacyCollectedDataTypes: empty — no data types are declared as collected at the framework level.

See Also

• Process Definition Guide
• API Keys Guide
• TrustX API ReferenceAPI