iOS SDK quick start with Identity Orchestration-powered backend

This guide describes how to quickly integrate Detection and Response services into your iOS application and obtain real-time risk recommendations using Identity Orchestration journeys. This guide covers the client-side integration (using the Detection and Response SDK and the Identity Orchestration SDK) and the journey configuration needed to complete the flow.

How it works

The flow starts with the user navigating to your iOS app (1). The Detection and Response (DRS) SDK and the Identity Orchestration (IDO) SDKs get initialized (2 & 3). The DRS SDK starts streaming telemetry data to Mosaic (4). The application requests a session token (5), the DRS sends a request to the Mosaic server (6) and receives a session token (7), which is then returned to the application (8).

When a user performs a high risk action (9), the application notifies the IDO SDK to start a journey (10). The IDO SDK invokes a journey (11). Mosaic reaches the risk recommendation step (12) and sends a request to the DRS engine (13). As soon as a recommendation is returned (14), IDO processes the risk (15) and passes this data to the IDO SDK (16), which then forwards it to the application (17). The application proceeds depending on results (18).

Requirements

• iOS 13+
• Xcode 11+

Before you start

• Allow Mosaic IPs and domains on your network
  
• Extend the Content-Security-Policy header, if CSP is enabled on your web server
  

Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the Admin Portal (if you don’t have one yet).

1. From Applications , click Add application .
2. Add the friendly application name to display in the Admin Portal.
3. Configure a client: its display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).

   Note

   These fields are required for all Mosaic apps, but won’t be used for Detection and Response or Identity Orchestration journeys.

4. Click Add to create your client. This will automatically generate your client credentials.

Step 2: Orchestrate the backend logic

Identity Orchestration can handle the business logic responsible for obtaining risk recommendations for sensitive events. This includes the following configuration steps:

1. Store client credentials
2. Create a web function
3. Configure journey steps

1. Store client credentials

Start by saving the client credentials you've acquired in Step 1 with Identity Orchestration. This step is required in order to authorize journey calls.

1. Navigate to Admin Portal > Orchestration > Keys and Credentials > Credentials and select +Add credentials .
2. Provide an alias and input client ID and secret.

See Key and credentials for more details.

2. Create a web function

Create a new web function that calls the Trigger action endpoint. See Web service function for more details.

1. Navigate to Admin Portal > Orchestration > External Connections and select +Add > API > Web service function .
2. Provide a function name, e.g., trigger_action_for_user
3. Add function argument # 1:
   • Argument name: session_token
   • Argument description: DRS SDK session token
   • Type description: string
4. Add function argument # 2:
   • Argument name: action_type
   • Argument description: Client provided action type
   • Type description: string
5. Add function argument # 3:
   • Argument name: user_id
   • Argument description: Identifier of an authenticated user
   • Type description: string
6. Add function argument # 4:
   • Argument name: correlation_id
   • Argument description: Interaction ID in your app
   • Type description: string
7. Configure the format:
   • Request URI: https://api.transmitsecurity.io/risk/v1/action/trigger-action?get_recommendation=true
   • HTTP request method: POST
   • Request body:
     Copy

     Copied

     {
         "session_token": "${session_token}",
         "action_type": "${action_type}",
         "correlation_id": "${correlation_id}",
         "user_id": "${user_id}"
     }

   • Request header:
     • Name: Content-Type
     • Value: application/json
8. Configure authentication:
   • Authentication Type: OAuth 2 Client Credentials Grant
   • URL: https://api.transmitsecurity.com/oidc/token
   • Credentials alias: select the alias created in Step 2.1
   • Scope: offline_access
   • Resource: https://risk.identity.security
9. Set the response format to JSON object .
10. Save a function.

3. Configure journey steps

Configure an identity journey for obtaining risk recommendations and exporting a result.

1. In the Admin Portal, go to the Orchestration > Identity journeys and create a new Client SDK journey. Provide a name, e.g., risk-recommendation .
2. Add the Invoke a Web Service step and configure it to use the web function defined in Step 3.2 .
   • Configure the step to set its result into the output variable (e.g., risk_recommendation ).
   • Configure the step to retrieve the input parameters provided by the client in the journey (see Step 6 ) as follows:
     • session_token : @policy.request().params["session_token"]
     • action_type : @policy.request().params["action_type"]
     • user_id : @policy.request().params["user_id"]
     • correlation_id : @policy.request().params["correlation_id"]
3. Add the Provide JSON Data step and set the Data to Send to:
   Copy

   Copied

    {
       "risk_recommendation": "risk_recommendation"
    }

4. Add the Complete Journey step.

Your journey will look as follows:

Step 3: Add SDKs to project

Add the SDKs to your project so your application can access all the detection and response functionality and invoke identity journeys. Install SDKs as dependencies using Swift Package Manager.

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

Step 4: Initialize SDKs

Initializing the SDKs configures them to work with your client ID. It also allows setting the base URL for the SDKs to use, whether a Mosaic-provided path or your own proxy. In case of Detection and Response, it starts streaming telemetry data upon SDK initialization.

<?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>https://api.transmitsecurity.io/</string> <!-- Default -->
		<key>clientId</key>
		<string>[CLIENT_ID]</string>
	</dict>
</dict>
</plist>

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        TSAccountProtection.initializeSDK()
        TSIdo.initializeSDK()
        return true
    }
}

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        TSAccountProtection.initialize(clientId: [CLIENT_ID])
        TSIdo.initialize(
            clientId: Env.clientId,
            options: .init(serverPath: Env.baseUrl)
        )
        return true
    }
}

struct ExampleApp: App {

    init() {
        TSAccountProtection.initialize(clientId: [CLIENT_ID])
        TSIdo.initialize(
            clientId: Env.clientId,
            options: .init(serverPath: Env.baseUrl)
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Step 5: Create session token

Obtain a DRS session token by executing the code below. This step occurs once per application lifecycle. Save the received session token in order to obtain risk recommendations in the next step (Step 6).

TSAccountProtection.getSessionToken { token in
    debugPrint("[DEBUG]: DRS session token: \(token)")
}

Step 6: Invoke journey

To obtain risk recommendations, the journey (created in Step 2) should start in response to sensitive user interactions, such as payments. Your application should present a button and call the below on user click. Along with the journey invocation, pass:

• session_token received in Step 5
• action_type from our list of actions that represents a high risk action the user attempts to perform
• user_id that represents a hash of the user logged into the app. The actual user ID should not be sent (this journey assumes the user has already authenticated in your app)
• correlation_id of the interaction

let params: [String: Any] = [
    "user_id": "[USER_ID]",
    "action_type": "[ACTION_TYPE]",
    "session_token": "[SESSION_TOKEN]",
    "correlation_id": "[CORRELATION_ID]"
]

// Start the journey
TSIdo.startJourney(journeyId: "[JOURNEY_ID]",
                   options: .init(additionalParams: params,
                                  flowId: "[FLOW_ID]"))

// Handle start journey response:
func TSIdoDidReceiveResult(_ result: Result<IdentityOrchestration.TSIdoServiceResponse, IdentityOrchestration.TSIdoJourneyError>) {
    isLoading.send(false)

    switch result {
    case .success(let response):
        handleIdoResponse(response)
    case .failure(let error):
        handleJourneyError(error)
    }
}

private func handleIdoResponse(_ response: IdentityOrchestration.TSIdoServiceResponse) {
    // Get journey step id
    guard let responseStepId = response.journeyStepId else { debugPrint("[DEBUG]: No step id found in response"); return }
    // Get response data
    guard let actionData = response.data else { debugPrint("[DEBUG]: No data found in response object"); return }

    ...
    // Handle UI based on the step id
}

Step 7: Handle recommendation

Mosaic signals journey completion by setting the journeyStepId property to Rejection.type or Success.type. The IDO SDK returns recommendation data (idoServiceResponse.data.json_data) to the application to proceed accordingly.