Orchestration guide: iOS SDK

This guide describes how to quickly integrate Identity Orchestration journeys into your iOS application.

See SDK reference

Introduction

The Orchestration SDK enables client-side developers to build user experiences that interact with journeys.

Each journey contains a business workflow, such as login or secure user onboarding. It consists of backend steps, such as data processing or invoking external systems, and client-facing steps, such as a login form or document verification. The SDK allows the client application to present screens and prompt for user input, and then send this information back to the journey for further processing.

Whenever the client-side interaction requires additional Mosaic platform capabilities, such as passkeys or risk detection, the developer needs to activate the appropriate SDK module to perform the step and collect the required input. This allows separation of concerns between the journey workflow handling, and the specific capability used.

SDK lifecycle

Regardless of journey logic, the SDK lifecycle consists of the following:

The above is reflected in the following workflow diagram:

Before you start

Before the SDK can start running journeys, make sure to:

☐   Coordinate with the journey developer (regarding journey ID, steps, expected data, etc).
☐   Obtain the Client ID that identifies the app, from the app settings in the Admin Portal
☐   Allow Mosaic IPs and domains on your network

Step 1: Installation

The Mosaic iOS SDK is broken down into several modules that can be consumed using Swift Package Manager or Cocoa pods. The Mosaic Identity Orchestration SDK is available here.

• To use Swift Package Manager : install the SDK as a dependency in your Package.swift .
• To use CocoaPods : specify the SDK in your Podfile .

dependencies: [
    .package(url: "https://github.com/TransmitSecurity/identityOrchestration-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
]

pod 'IdentityOrchestration', '~> 1.0.1'

Step 2: Initialize SDK

Initializing the SDK configures it to work with your client ID, which is the context under which the entire journey is executed. It also allows setting the base URL for the SDK to use, whether a Mosaic-provided path or your own proxy.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>credentials</key>
	<dict>
		<key>baseUrl</key>
		<string>[BASE_URL]</string> <!--Default is https://api.transmitsecurity.io.-->
		<key>clientId</key>
		<string>[CLIENT_ID]</string>
	</dict>
</dict>
</plist>

do {
    try TSIdo.initializeSDK()
    TSIdo.delegate = self  // Allows to process server responses in async manner
} catch {
    debugPrint("[DEBUG]: \(error)")
}

TSIdo.initialize(
    clientId: Env.clientId,
    options: .init(serverPath: Env.baseUrl)
)

Step 3: Start journey

Starting a journey is usually a response to some user interaction, such as clicking a login or sign-up button. The start parameters indicate which journey to start, and optionally pass additional parameters if the journey expects them.

For example, if the client app uses email as the user identifier and caches it locally after sign-up, it can pass it to the journey as userEmail. The journey can reference it using this expression @policy.request().params.userEmail

TSIdo.startJourney(journeyId: <journey name>,
                   options: .init(additionalParams: <additional-params>, // Additional params
                                  flowId: <flow-id>))

Step 4: Handle service response

After starting the journey, the client app waits for the TSIdoServiceResponse. It will contains all the information the client needs in order to determine what to do next.

To handle the service response, the client app needs to:

1. Select a handler based on the step
2. Use the data provided by the journey
3. Respond to the journey with requested input

1. Select handler

Upon receiving the TSIdoServiceResponse, launch a handler that executes the relevant step by switching/selecting on the TSIdoServiceResponse.journeyStepId parameter. It will either contain one of these enums or .custom("step-id") where step-id is the Step ID configured in the Login Form or Get Information from Client step. Each handler should process the data, display whatever UI is needed, and call submitClientResponse() when the interaction is concluded.

This is how the app code would dispatch handlers based on this property:

private func handleJourneyActionUI(for response: IdentityOrchestration.TSIdoServiceResponse) {
    guard let responseStepId = response.journeyStepId else { debugPrint("[DEBUG] No step id found in response"); return }
    guard let actionData = response.data else { debugPrint("[DEBUG] No data found in response object"); return }
    
    switch responseStepId {
    case .information:
        // Show information screen
    case .emailOTPAuthentication:
        // handle email OTP step
    case .custom("main_login_form"):
        // handle login form with the ID main_login_form
    case .custom("user_info_form"):
        // handle collect onformation step with the ID user_info_form
    default:
        debugPrint("[DEBUG] Unsupported step: \(responseStepId)")
    }
}

2. Use data sent from journey

Inside the handler function, the app code should render a UI that fits the specific step, and use information from the data property if it was provided in the TSIdoServiceResponse object. This data is described in each step guide.

Let's see an example for a Register Passkeys step. TSIdoServiceResponse will include journeyStepId set to .webAuthnRegistration and a data object containing the user identifier and other WebAuthn configuration. This data can be used for calling the webauthn (passkey) registration module, as shown below:

// The actionData is taken from the TSIdoServiceResponse object
let actionData = response.data

let username = actionData["user"] as? [String: any]
let allowCrossPlatformAuthenticators = actionData["allow_cross_platform_authenticators"] as? [Bool: any]
let registerAsDiscoverable = actionData["register_as_discoverable"] as? [Bool: any]
let displayName = actionData["display_name"] as? [String: any]

// Now activate the passkey registration module, and return a response
TSAuthentication.shared.registerWebAuthn(username: username, displayName: displayName) { result in
    switch result {
    case .success(let response):
        TSIdo.submitClientResponse(clientResponseOptionId: .clientInput,
                                   data: ["webauthn_encoded_result": response.result])
    case .failure(let error):
        TSIdo.submitClientResponse(clientResponseOptionId: .fail)
        
        debugPrint("[DEBUG] Error: \(error)")
    }
}

3. Respond with collected data

Once the user interaction is concluded, the handler should collect the response data and submit it using submitClientResponse(). This call yields control back to the journey, and returns with a new TSIdoServiceResponse once the journey reaches the next client-facing step.

The call parameters are the collected data, and a response option identifier. We’ll talk more about these below. For now, let's follow the Register Passkeys example of making this call.

let data = ["webauthn_encoded_result": encodedRegistrationResult]
TSIdo.submitClientResponse(
    clientResponseOptionId: .clientInput,
    data: data
)

let data = ["webauthn_encoded_result": encodedAuthenticationResult]
TSIdo.submitClientResponse(
    clientResponseOptionId: .custom("passkey"),
    data: data
)

Step 5: Complete journey

The orchestration service signals journey completion by setting the journeyStepId property to rejection or success. The specific enum for each SDK is described in the Step 3.1 above. If successful, the token property contains a token as a proof of journey completion.

Next steps

The SDK also supports the features below. For more info, talk to your Transmit Security representative.

• Generating a debug pin for the journey debugger
• Local console logs
• Resources URIs as part of SDK initialization