Transaction Signing with Mobile Biometrics

Client SDK

Mobile approve

SSO

Sub-journey

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.

Note

For SDK setup instructions, see the Android quickstart and the iOS quickstart (skip Steps 3 and 4). For Android, ensure compileSdk is 34+ and minSdk is 23+.

Configuration

Field	Description
External user ID	Expression to retrieve the user’s identifier (e.g., email, username, or phone number) from the journey context or custom query parameters: If the user has already authenticated in the journey, the step can infer the external user ID from the journey context by configuring the External User ID field with the `@policy.userContext().external_user_id` expression. If the user has not authenticated in the journey, an external user ID must be provided to the step as a custom query parameter in the start journey call. To retrieve the ID from the query parameters, configure the External User ID field to use the `@policy.request().params.external_user_id` expression.
Approval data	A JSON object containing a flat list of up to 10-string properties used to derive the Passkey challenge. Each value must be a string. Allowed characters: alphanumeric, spaces, and the special characters `.` , `_` and `-`. This object is dynamically generated based on transaction details, such as amount, currency, and transaction ID.
Error Output Variable	Name of the variable that stores any errors returned by action
Failure Behavior	Determines the behavior in case of failure, which either aborts the journey or proceeds to a failure branch of the control flow (default).
Custom Branches	Additional journey branches supported for this step. The client can select a branch by returning the branch ID. For each branch, you can define a schema for the information that the client is expected to return (used by the code generator and for autocompleting journey expressions) and a display name to label it in the editor.
Branch Output Variable	Name of the variable used to store the data returned by the client, which can be used in subsequent journey steps.
Cancel Behavior	Determines the behavior of client cancellation, which either aborts the journey (default) or proceeds to a cancel branch of the control flow

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
  )

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.