MFA SDK - Mobile (iOS)

TrustBuilder Safe-T SDK for mobile enables the integration of MFA capabilities into a mobile app.

It provides a set of functions that allow applications to manage authentication and transaction confirmation flows.

The SDK exposes the following functionalities:

Validate an authentication request
Confirm a transaction
Retrieve pending operations requiring user action
Reject an operation
Register a secure token for a given login
Generate an activation code to register a new secure token
Update the push notification identifier (Push ID) of the device
Retrieve secure tokens stored locally on the device
Change secret code
Reset a blocked secret code
Generate a reset code
Change the display name of a secure token

The SDK also provides in-app MFA interactions, allowing authentication and transaction flows to be handled directly within the application UI:

Request authorization for authentication or transaction confirmation within the app
Validate an authentication request in-app
Confirm a transaction in-app
Register biometric authentication as a secure factor

This integration guide uses specific terms:

Device
The device represents the possession factor of the user. It refers to the mobile device on which the application and secure token are installed.

Secure Token
A cryptographic object stored on a registered device that enables authentication.

Transaction confirmation
A process where the user explicitly approves a transaction in its specific context. The generated authentication code binds the transaction context to the user’s credentials, making it unforgeable and usable as a proof of consent.

Requirements

Download TrustBuilder sample app for iOS
Xcode: latest version currently supported by Apple
Minimum deployment target: iOS 15.0
The mobile application must be registered as a custom application in TrustBuilder administration console. You should provide Service Account JSON and Application ID to administrator. Once the application is registered in the TrustBuilder system an App Alias is automatically generated. It is required during SDK initialization.

Installation

Xcode project configuration: when creating your Xcode project, ensure that the Minimum Deployments is set to iOS 15.0 at minimum.
Add the TrustBuilder MFA library file (.xcframework) to your project with the correct version.
Sample application configuration: The sample app reads its configuration from the app's Info.plist. Add the following keys:
CODE
```
<key>App_Alias</key>
<string>your_app_alias</string>
<key>App_Id</key>
<string>com.yourcompany.yourapp</string>
<key>App_Name</key>
<string>YourAppName</string>
```
- app_Alias -> the unique identifier of the custom application declared in TrustBuilder console (See Requirements)
- app_Id → the bundle identifier of the application.
- app_Name -> the display name of the application.

Initialization

There is one interface to implement:

Implementing IHost interface
IHostdescribes general properties of the host application and device:

CODE

import TrustBuilderMfaLibSwift
import UIKit

public struct Host: IHost {
    public var appInfo: ApplicationInfo
    public var osInfo: OsInfo
    public var serial: String
    public var name: String
    public var type: String
    public var appAlias: String

    public init() {
        appInfo = ApplicationInfo(
            id: Bundle.main.object(forInfoDictionaryKey: "App_Id") as! String,
            name: Bundle.main.object(forInfoDictionaryKey: "App_Name") as! String,
            version: "1",
            type: "iOS SDK"
        )
        osInfo = OsInfo(
            name: "iOS",
            version: UIDevice.current.systemVersion
        )
        appAlias = Bundle.main.object(forInfoDictionaryKey: "App_Alias") as! String
        serial = "serial"
        name = "localhost"
        type = "IW_MOBILE"
    }
}

Property	Description
`serial`	Hardware serial identifier
`name`	Name given to the secure token on this host
`type`	Token type - always `"IW_MOBILE"` for iOS
`appAlias`	Custom application alias (see Requirements)
`appInfo.id`	Application bundle identifier
`appInfo.name`	Application display name
`appInfo.version`	Application version
`appInfo.type`	Build type (e.g. `"iOS SDK"`)
`osInfo.name`	OS name (`"iOS"`)
`osInfo.version`	iOS version string

Creating the library instance
The TrustBuilderMfaLib instance should be a singleton, created once and reused across activities:

CODE

import TrustBuilderMfaLibSwift

class TrustBuilderMfaLibHolder {
    static var instance: TrustBuilderMfaLibHolder = TrustBuilderMfaLibHolder()

    let clientLib: TrustBuilderMfaLib

    private init() {
        clientLib = TrustBuilderMfaLib(host: Host())
    }

    public static func getClientLib() -> TrustBuilderMfaLib {
        return instance.clientLib
    }
}

General principles

Use Case pattern

The SDK exposes its features as use cases. There are two types:

<SingleUseCase> → one-step use case: it exposes a single execute function to process it.
<UseCase> → two-step use case: it exposes two functions setup and execute to process it. This allows the management of data to be entered or read by the user (typically user credentials management).

The naming format of the methods exposed by the TrustBuilder MFA library looks like this:

start<UseCaseName>(param: UseCaseNameParams);

Example:

CODE

let authentication = try clientLib.startAuthentication(param: authenticationParams)
let setup = await authentication.setup();

let credValue: CredValue = CredValue(credType: .SECRET_CODE, value: Array(secretCode .utf8))
let execute = try await authentication.execute(input: credValue)

Authentication flows

There are two authentication flows:

Out-Of-Band → the authentication request is initiated from a web channel and validated on the mobile.
In-App → the authentication request is initiated from the current application and validated in the current application.

Some exposed methods are different depending on the flow type.

Features implementation

This section describes the features implemented in the sample application available in the TrustBuilder MFA Swift SDK.

For now, the TrustBuilder MFA library is named ClientLib.

Validate an authentication request

Out-Of-Band authentication

Use case name	Authentication
Use case type	Use case
Description	Authenticate a user: this generates a One-Time-Password and calls TrustBuilder server to validate it.
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `appAlias`(string) → the alias of the application in Trustbuilder from which the user is authenticated `sessionId` (string) → the identifier of the authentication session or sealing session `scope` (AuthScope) → the scope of use of the generated challenge and the OTP.
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let authentication = try clientLib.startAuthentication(param: authenticationParams) let setup = await authentication.setup(); if (setup.isError == true) { // Handle Error } else { //Display Credential Provider let execute = try await authentication.execute(input: credValue) }` See the source code of the sample application for additional information

In-App authentication

Use case name	InAppAuthentication
Use case type	UseCase
Description	Authenticate a user in the current application. This generates a token if the authentication is successful. IN-APP
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `sessionId` (string) → the identifier of the authentication session or sealing session `appAlias` (string) → the alias of the application in Trustbuilder from which the user is authenticated `scope` (AuthScope) → the scope of use of the generated challenge and the OTP.
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let inAppAuthentication = try clientLib.startInAppAuthentication(param: inAppAuthenticationParams) let setup = await inAppAuthentication.setup(); if (setup.isError == true) { // Handle error } else { // Display Credential Provider let execute = try await authentication.execute(input: credValue) } else { //Display Credential Provider let execute = try await inAppAuthentication.execute(input: credValue) }` See the source code of the sample application for additional information

Activate a Secure Token

Use case name	SecureTokenEnrollment
Use case type	Use case
Description	Activate a Secure Token for a given login (enrollment process)
Input parameter(s)	`code` (string) → the activation code
Errors	IW_FORBIDDEN_ERR IW_INVALID_SECRET_CODE_FORMAT IW_CORE_CNX_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let secureTokenEnrollmentParams = SecureTokenEnrollmentParams( code: code ) let secureTokenEnrollment = try clientLib.startSecureTokenEnrollment(param: secureTokenEnrollmentParams) let setup = await secureTokenEnrollment.setup(); if (setup.isError == true) { // Handle error } else { // Display Credential Provider handling if this is an first enrollment or an addition of trusted device let execute = await secureTokenEnrollment.execute(input: credValue) }` See the source code of the sample application for additional information

Retrieve all Secure Tokens

Use case name	SecureTokensListing
Use case type	SingleUseCase
Description	Retrieve the secure tokens stored in the local storage
Input parameter(s)	/
Errors	IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR See errors descriptions
Example	JAVA `let useCase = clientLib.startSecureTokensListing() let response:SecureTokensListingResult = try await useCase.execute()` See the source code of the sample application for additional information

Retrieve the pending operations

Use case name	PendingAuthSessionsRetrieval
Use case type	SingleUseCase
Description	Retrieve the pending operations i.e operations that need validation to be processed
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let useCase = try clientLib.startPendingAuthSessionsRetrieval(param: PendingAuthSessionsRetrievalParams(tknAlias: tknAlias)) let response = try await useCase.execute()` See the source code of the sample application for additional information

Reject an operation

Use case name	AuthSessionCancellation
Use case type	SingleUseCase
Description	Reject an authentication request or a transaction confirmation request
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `sessionId` (string) → the identifier of the transaction `reason` (CancelReason) → reason for cancellation (`"NONE", "DUPLICATE", "FRAUDULENT", "ABANDONED"`)
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_OTP_ERR IW_INV_AUTH_SESSION_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let cancelReason = CancelReason(rawValue: reason) let useCase = try clientLib.startAuthSessionCancellation(param: AuthSessionCancellationParams(tknAlias: tknAlias, sessionId: sessionId, reason: cancelReason!)) let response = try await useCase.execute()` See the source code of the sample application for additional information

Confirm a transaction

Out-Of-Band transaction

Use case name	Sealing
Use case type	UseCase
Description	Confirm an electronic transaction on top of authentication. This displays the business data provided by the Service Provider. Then this generates One-Time-Password and calls TrustBuilder server to validate it.
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `appAlias`(string) → the alias of the application in Trustbuilder from which the user is authenticated `sessionId` (string) → the identifier of the transaction
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_BUSINESS_DATA_IS_EMPTY_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let sealing = try clientLib.startSealing(param: params) let setup = await sealing.setup(); if (setup.isError == true) { // Handle error } else { // Display Business Data // Display Credential provider let execute = try await sealing.execute(input: credValue) }` See the source code of the sample application

In-App transaction

Use case name	InAppSealing
Use case type	UseCase
Description	Confirm an electronic transaction on top of authentication in the current application. This generates a token if the authentication is successful. IN-APP
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `appAlias`(string) → the alias of the application in Trustbuilder from which the user is authenticated `sessionId` (string) → the identifier of the authentication session or sealing session
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_AVAILABLE_AUTH_METHOD_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_AUTH_SESSION_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_BUSINESS_DATA_IS_EMPTY_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let inAppSealing = try clientLib.startInAppSealing(param: params) let setup = await inAppSealing.setup(); if (setup.isError == true) { // Handle error } else { // Display Business Data // Display Credential provider let execute = try await inAppSealing.execute(input: credValue) }` See the source code of the sample application for additional information

Request an authorization

Use case name	AuthorizationRequest
Use case type	SingleUseCase
Description	Request an authorization for an in-app authentication or for an in-app transaction confirmation. It will provide a sessionId to execute the requested operation. IN-APP
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `appAlias`(string) → the alias of the application in Trustbuilder from which the user is authenticated `Authorizescope` → the scope of the authorization request “AUTH”: authentication request “SEAL”: transaction confirmation request “SESSION”: session request `sealData` (SealBusinessData)→ (only if `Authorizescope`=SEAL) the business data to display and seal
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_USR_HAS_NO_ACCESS_ERR IW_TKN_IS_UNKNOWN_ERR IW_INV_OTP_ERR IW_TKN_IS_BLOCKED_ERR IW_CNX_IS_UNKNOWN_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let authScope = AuthorizationScope(rawValue: scope) let useCase = try clientLib.startAuthorizationRequest(param: AuthorizationRequestParams(tknAlias: tknAlias, cnxAlias: cnxAlias, scope: authScope!, sealData: SealBusinessData(format: .md, value: "my business data value"))) let response = try await useCase.execute()` See the source code of the sample application for additional information

Generate an activation code

Use case name	ActivationCodeGeneration
Use case type	UseCase
Description	Generate an activation code to activate a new Secure Token on another device
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let useCase = try clientLib.startActivationCodeGeneration(param: params) let setup = await useCase.setup(); if (setup.isError == true) { // Handle error } else { // Display Credential provider let execute = try await useCase.execute(input: credValue) }` See the source code of the sample application for additional information

Change Secret Code

Use case name	SecretCodeChange
Use case type	UseCase
Description	Change a secret code (the user knows the current secret code but wants to change its value)
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR IW_INV_SECRET_CODE_FORMAT See errors descriptions
Example	JAVA `let useCase = try clientLib.startSecretCodeChange(param: params) let setup = await useCase.setup(); if (setup.isError == true) { // Handle error } else { // Display Credential provider to acquire current and new secret code let execute = try await secretCodeChange.execute(input: credValues) }` See the source code of the sample application for additional information

Reset a Secret code

Use case name	secretCodeReset
Use case type	UseCase
Description	Reset a blocked secret code
Input parameter(s)	`tknAlias` (string) → unique identifier of the secure token `code` (string) → the Reset Code encoded in Base32
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_CODE_ERR IW_INV_SECRET_CODE_FORMAT IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	SWIFT `let params = SecretCodeResetParams(tknAlias: tknAlias, code: code) let secretCodeReset = try ClientLibHolder.getClientLib().startSecretCodeReset(param: params) let setup = await secretCodeReset.setup() // → ask the user to define their new secret code (NEW mode) let credValue = CredValue(credType: .SECRET_CODE, value: Array(secretCode.utf8)) let result = await secretCodeReset.execute(input: credValue)` See the source code of the sample application

Generate a Reset code

Use case name	ResetCodeGeneration
Use case type	SingleUseCase
Description	Generate a reset code and send it by email to the user An error is returned: if the tenant security policy prevents this action. if the user does not have an email address associated to his profile
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_FORBIDDEN_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let useCase = try clientLib.startResetCodeGeneration(param: ResetCodeGenerationParams(tknAlias: tknAlias)) let response = try await useCase.execute()` See the source code of the sample application for additional information

Change the Secure token name

Use case name	SecureTokenFriendlyNameUpdate
Use case type	SingleUseCase
Description	Update the friendly name of the secure token -optional, used to identify more easily the secure token
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `tknName` (string) → the current secure token name to update
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let useCase = try clientLib.startSecureTokenFriendlyNameUpdate(param: SecureTokenFriendlyNameUpdateParams(tknAlias: tknAlias, tknName: tknName)) let response = try await useCase.execute()` See the source code of the sample application for additional information

Update the push ID

Use case name	pushIdRegistration
Use case type	SingleUseCase
Description	Update the push ID generated for the host application
Input parameter(s)	`tknAlias`(string) → unique identifier of the secure token `tknPushId` (string) → the current push notifications ID to update
Errors	IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_USR_IS_BLOCKED_ERR IW_USR_IS_UNKNOWN_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	JAVA `let useCase = try clientLib.startPushIdRegistration(param: PushIdRegistrationParams(tknAlias: tknAlias, tknPushId: pushId)) let response = try await useCase.execute()` See the source code of the sample application for additional information

Register a biometric factor

Use case name	BiokeyRegistration
Use case type	UseCase
Description	Register biometric data. A key pair is generated in the keychain to be used on a successful biometric matching on the trusted device. The public key is provided to inWebo for a verification of the challenge signature during authentication.
Input parameter(s)	`tknAlias` (string) → the alias of the secure token used
Errors	IW_USR_IS_UNKNOWN_ERR IW_USR_IS_BLOCKED_ERR IW_TKN_IS_UNKNOWN_ERR IW_TKN_IS_BLOCKED_ERR IW_FORBIDDEN_ERR IW_INV_CRED_ERR IW_BLOCKED_CRED_ERR IW_BIOKEY_IS_ALREADY_REGISTERED_ERR IW_CHALLENGE_SIGNATURE_IS_NOT_VERIFIED_ERR IW_INV_OTP_ERR IW_CORE_CNX_ERR IW_TKN_STORAGE_ERR IW_UNKNOWN_ERR IW_LOCAL_TKN_NOT_FOUND_ERR See errors descriptions
Example	SWIFT `let biokeyRegistration = try clientLib.startBiokeyRegistration(param: biokeyRegistrationParams) let setup = await biokeyRegistration.setup(); if (setup.isError == true) { // Handle error } else { // Display Disclaimer // Display Credential Provider // Generate RSA key pair in <Secure Element> let execute = await biokeyRegistration.execute(input: credValue) }` See the source code of the sample application

Data Types

Data	Description	Parameters
CredentialProvider	Object containing the information needed to request a credential from the user	credMode: NEW \| EXISTING NEW: request to define credential EXISTING: request to enter the credential for validation credType: <CredType> see CredType below credProperties SecretCodeFormat: format of the requested secret code BioChallenge: challenge to be signed by the private key of the <SecureElement>
CredValue	Object containing the credential data	value: credential value credType: <CredType> see CredType below
CredType	Credential type	SECRET_CODE \| BIO SECRET_CODE: request to enter a secret code BIO: request to enter the bio (Face, finger, ...)
BoolResult	Object encapsulating a Boolean	result: Boolean
SecureToken	Data of a secure token exposed by the library	tntAlias: alias of the tenant to which the secure token belongs login: login of the user to which the secure token belongs alias: identifier of the secure token
AuthSessionDto	Data of an authentication session or a sealing session	tntAlias: alias of the tenant linked to the session login: login of the user linked to the session cnxAlias: alias of the connector on which the user must authenticate cnxName: the name of the connector authCreated: creation date of the session authExpired: expiry date of the session authValue: session identifier authScope: scope of use of the session. type <Scope>