Transaction Signing with Mobile Biometrics

Prompts the user to approve a financial transaction using mobile biometrics (e.g., fingerprint, Face ID).

Description

This step enables users to approve financial transactions by authenticating with their mobile biometric credentials (e.g., Face ID, fingerprint). These credentials must be pre-registered using the Register Mobile Biometrics step.

Use cases include:

• Approving financial transactions (e.g., payments, money transfers).
• Authorizing sensitive actions that require explicit user consent.
• Strengthening security while preserving a seamless user experience.

The signing process starts when the client initiates the journey by sending approvalData (a flat JSON object with transaction details like amount, recipient, and currency) to the Mosaic journey in the start call.

When the journey reaches the Transaction Signing with Mobile Biometrics step, a challenge is derived from approvalData with added randomness, ensuring the cryptographic signature securely binds it to the transaction details.

The step instructs the client to use biometrics to display the approval data sign the generated challenge. The client calls the Authentication SDK for iOS or Authentication SDK for Android with approvalData, prompting the user for biometric authentication.

The SDK signs the challenge, then sends the signed result back to the journey for validation via the Orchestration SDK for iOS or Orchestration SDK for Android.

On successful authentication:

• Mosaic verifies the signed challenge.
• Authentication tokens (ID or access tokens) are issued with approvalData embedded in their claims.
• The signed result is stored in the configured output variable.
• The journey advances to the next step.

On authentication failure (e.g., invalid biometrics, timeout):

• The journey either redirects to a failure branch or terminates, based on configuration.
• The client may provide fallback options, such as retrying or using an alternative authentication method.

To support transaction signing with mobile biometrics, you'll need to:

• Implement biometric registration, as described in Register Mobile Biometrics .
• Call the Authentication SDK for iOS or Authentication SDK for Android for biometric authentication.
• Use the Orchestration SDK for iOS or Orchestration SDK for Android to submit the authentication result to the journey.
• Configure the journey step: Mobile Biometrics Authentication .

Configuration

Example

A user of a mobile banking application needs to approve a payment transaction of $1,000 to "Merchant A". The app displays the transaction details—amount, recipient, and currency—to the user for confirmation, which the user digitally signs by authenticating using biometrics (Face ID, fingerprint).

To do so, the client initiates the transaction signing journey by sending approvalData to Mosaic. The approvalData is a JSON object containing the transaction details. For example:

{
  "amount": "1000",
  "currency": "USD",
  "recipient": "Merchant A",
  "transaction_id": "txn_12345"
}

Once the journey reaches the Transaction Signing with Native Biometrics step, the step instructs the client to authenticate the user with mobile biometrics. The client application invokes the Android or iOS Authentication SDK method authenticateNativeBiometrics(), passing:

• approvalData (transaction details).
• user_identifier (the authenticated user).
• challenge (a unique security challenge).

On Android, this may include fingerprint, face recognition, or a device PIN fallback. On iOS, it may involve Face ID, Touch ID, or a device passcode.

// Initiates native biometric authentication to approve the transaction
TSAuthentication.approvalNativeBiometrics(activity, external_user_ID, challenge,
    object : TSAuthCallback<TSNativeBiometricsApprovalResult, TSNativeBiometricsApprovalError> {

        // Handles authentication failure
        override fun error(error: TSNativeBiometricsApprovalError) {
            Log.e(TAG, "Native biometrics approval error: ${error.errorMessage}")
        }

        // Handles successful biometric authentication
        override fun success(result: TSNativeBiometricsApprovalResult) {
            // Submits the signed result to the journey using the Orchestration SDK
            TSIdo.submitClientResponse(
                TSIdoClientResponseOptionType.ClientInput.type,  // Specifies that client input is being sent
                BiometricsApproval(result.keyId(), external_user_ID, result.signature()), // Sends the signed challenge and key ID
                callback // Handles the journey response
            )
        }
    }
)

// Data class representing the signed biometrics result
data class BiometricsApproval(
    val publicKeyId: String, // Unique identifier for the cryptographic key
    val userIdentifier: String, // External user ID used in the journey
    val signedChallenge: String // Signed challenge proving user consent
)

// Initiates biometric authentication for transaction signing
TSAuthentication.shared.approvalNativeBiometrics(username: "[External_user_ID]", challenge: "[CHALLENGE]") { response in

    switch response {

    case .success(let result):
        // If authentication is successful, construct the signed result data
        let data: [String: String] = [
            "publicKeyId": result.publicKeyId,      // Unique identifier for the cryptographic key used
            "signedChallenge": result.signature,   // Cryptographic signature of the challenge, proving biometric consent
            "userIdentifier": username             // The user's identifier, required for journey validation
        ]

        // Submit the signed result to the journey for validation
        // This step ensures that the transaction is cryptographically linked to the user's biometric approval
        TSIdo.submitClientResponse(clientResponseOptionId: .clientInput, data: data)

    case .failure(let error):
        // If authentication fails (e.g., invalid biometrics, timeout, or user cancellation), log the error
        debugPrint("[DEBUG]: Mobile Biometrics Authentication failed with error: \(error)")

        // Depending on journey configuration, failure may trigger a retry, fallback authentication, or transaction denial
    }
}

If authentication is successful, the Mobile SDK returns a signed result, which includes:

• signedChallenge (the cryptographic proof of authentication).
• signedApprovalData (the signed transaction details).
• keyId (identifier for the cryptographic key used).

The client submits this signed result back to Mosaic IDO for validation. Mosaic validates the signed challenge, ensuring it corresponds to the approvalData. If validation succeeds, authentication tokens (ID Token and/or Access Token) are issued, embedding approvalData in the claims. The journey then proceeds to the next step.