Register Mobile Biometrics

Registers native mobile biometrics for the user using the client SDK

About client-facing steps

A journey is a sequence of steps that are executed when it's invoked by a client application (known as the "client"). Some steps require involvement from the client, such as to collect user input. Other steps, like validating a token, are executed in the backend by the Mosaic journey engine alone.

When invoked, the journey begins executing the steps while the client waits for further instructions. When a journey reaches a client-facing step, the journey asks the client for the required input and then waits for the client to respond. The client presents their own UI if user interaction is required, and returns input to the journey. The journey then proceeds in a similar manner until it's completed.

Description

This client-facing step is used to register biometric credentials on a user's mobile device for biometric authentication (e.g., Face ID). Once registered, users can login with biometrics using the Mobile Biometrics Authentication step.

Biometric credentials are bound to a specific user and Mosaic application. The user may be provided implicitly by the journey if the user is already authenticated; otherwise, a user identifier must be specified in the step configuration. Credentials should only be registered to a user that has verified their identity—for example, using email OTP, document verification, or externally using a legacy system.

When triggered, this step instructs the client to register biometric credentials on the device and provides the user identifier. The client then uses the Authentication SDK to perform the client-side registration, where the user identifier may be used as input to the registration call.

Once credentials are registered on the device, the SDK returns a registration result that includes the key ID and public key. The client sends this result back to the journey using the IDO SDK, and the step completes the registration in the platform. If successful, the journey proceeds to the next step. If it fails or is cancelled, the journey is either aborted or proceeds to the dedicated cancel or failure branches (if configured).

To support biometric registration, you'll need to:

• Configure the Register Mobile Biometrics journey step
• Implement the Authentication SDK calls required for registration, as described here
• Implement the IDO SDK call that submits the client response back to the journey (see Android IDO SDK reference or iOS IDO SDK reference )

Configuration

Example

Consider a journey that authenticates the user (e.g., using password) before initiating a biometric registration. In our example, the User Auth State is set to The user is already authenticated in the step configuration.

When executed, this step sends a callback to the client with the IDO service response object. It will have the journeyStepId set to registerNativeBiometrics and the data will include the user identifier. In the example below, the user identifier is used as input to the biometric registration call. Once registration is completed, the client submits the result back to the journey to complete the step.

// Stores the user identifier provided by the journey
val userId = idoResponse.responseData.optString("user_identifier") 
applicationContext?.let {
  // Registers biometric credentials on the device using the Authentication SDK
    TSAuthentication.registerNativeBiometrics(it, userId, object: TSAuthCallback<TSBiometricsRegistrationResult, TSBiometricsRegistrationError>{
        override fun error(error: TSBiometricsRegistrationError) {
            //handle registration error
        }

        override fun success(result: TSBiometricsRegistrationResult) {
            Log.d(TAG, "Biometrics registration success")
            // Submits the registration result back to the journey using the IDO SDK
            submitResponse(TSIdoClientResponseOptionType.ClientInput.type, BiometricsRegistrationResult(result.keyId(), result.publicKey()))
        }
    })
}

data class BiometricsRegistrationResult(val publicKeyId: String, val publicKey: String, val os: String = "Android")

guard let userId = response.data?["user_identifier"] as? String else {
            return debugPrint("[DEBUG]: No user identifier found in response")?
        }
        
        // Registers biometric credentials on the device using the Authentication SDK
        TSAuthentication.shared.registerNativeBiometrics(username: userId) { result in
            switch result {
            case .success(let response):

                var data: [String: Any] = [
                    "publicKey": response.publicKey,
                    "publicKeyId": response.publicKeyId,
                    "os": "ios"
                ]

                if let attestation = response.attestation {
                    data["attestation"] = attestation
                }

                // Submits the registration result back to the journey using the IDO SDK
                TSIdo.submitClientResponse(clientResponseOptionId: .clientInput, data: data)
            case .failure(let error):
                debugPrint("[DEBUG] Error: \(error)")
                TSIdo.submitClientResponse(clientResponseOptionId: .fail)
            }
        }