Face authentication

Face authentication is a next-generation biometric authenticator that combines speed, security, and user convenience. By leveraging Mosaic Identity Verification powered with AI-driven facial recognition, it helps organizations deliver frictionless access while ensuring the highest levels of fraud prevention and compliance. This solution is designed to work seamlessly across industries like finance, healthcare, and enterprise security, supporting both account recovery and day-to-day authentication scenarios.

• Account recovery : verify user identity with a live selfie to reset access securely.
• Login & access control : replace passwords with seamless face authentication for apps and systems.
• Fraud prevention : protect sensitive actions such as account changes.

What is Identity Verification?

Mosaic Identity Verification helps ensure that a user’s digital identity matches their real-world identity. A key part of this process is face authentication—comparing a live selfie against a trusted reference image vector.

Behind the scenes, Identity Verification evaluates the selfie capture through multiple checks: image quality, liveness detection, and biometric matching against the reference vector. It allows your app to confidently confirm that the person is who they claim to be and that they are physically present and not attempting to spoof the system with a photo, video, or mask. This ensures only legitimate users are granted access and authenticated in the app.

Learn more:

• Verification checks (face, liveness)
• PII handling & data privacy
• User consent & compliance

How it works

Face registration

To be able to authenticate with their face in the future, the logged-in user starts the face registration process in the app. The client invokes the face registration journey and upon reaching the Selfie Acquisition step step, Mosaic creates an Identity Verification session. The Orchestration (IDO) SDK passes the session's start_token to the client, which in turn invokes the Identity Verification (IDV) SDK. Having obtained a selfie, the Identity Verification SDK signals to the Orchestration SDK that it can resume the journey. As a next step, Mosaic registers the selfie (selfie_data) for the user identity specified earlier in the journey.

Face authentication

When a user requests to log in to the app using their face, the client invokes the authentication journey, where it first obtains the user identifier. Upon reaching the Selfie Acquisition step, Mosaic creates an Identity Verification session. The Orchestration (IDO) SDK passes the session's start_token to the client, which in turn invokes the Identity Verification (IDV) SDK. Having collected a selfie, the Identity Verification SDK signals to Orchestration SDK that it can resume the journey. As a next step, Mosaic validates this selfie (selfie_data) against a previously collected reference and authenticates the user in case the validation was successful.

Requirements

iOS:

• iOS 13+
• Xcode 11+

Android:

• Android 5+ (API level 21+)

Before you start

If this is your first time integrating with Mosaic, create an application in the Admin Portal as described here, then implement a login for the app using another authentication method, e.g. password authentication, since face authentication can only be enabled for existing users.

Step 1: Configure authenticator

The face authentication settings (Admin Portal > B2C Identity or B2B Identity > Authentication methods) allow you to configure the lockout policy in case of repeated failed attempts:

• Failed attempts : set the number of attempts allowed before triggering a lockout.
• Lockout duration : define how long the user must wait before they can try again.

For more about this authenticator, see Customize login methods.

As a next step, you can customize identity verification experience, for example, by changing the default language or image retention period (Admin Portla > Identity Verification > Customization). For details, see this guide.

Step 2: Build journeys

In the Admin Portal, go to B2C Identity or B2B Identity based on your setup, and open the Journeys section. Create two separate journeys—one for face registration and one for face authentication. You'll need to implement some client-side code for these journeys later (see Step 4).

Registration journey

This client SDK journey obtains a selfie from the logged-in user (e.g., after password authentication) and registers it as a reference vector in Mosaic. It can include the following actions:

1. Displays the login form ( Login form step) with enabled password authentication.
2. Logs in the user using password authentication ( Password authentication step).
3. Obtains a selfie image from the user ( Selfie acquisition step).

4. Registers the image vector as the reference for future face authentication flows ( Register face step). In our example, this step automatically obtains the user ID from the journey context since the user has authenticated earlier in the flow.
5. Depending on results, successfully completes the journey ( Complete journey step) or rejects access ( Reject access step).

Authentication journey

This client SDK journey prompts the user to authenticate with their face on their mobile device. It can include the following actions:

1. Displays the login form ( Login form step) with enabled face authentication option and obtains the external user ID from the form output as saves in the variable ( loginData.user_identifier )
2. Obtains a selfie image from the user ( Selfie acquisition step).
3. Verifies the selfie against the stored reference vector ( Face authentication step). In our example, the step obtains the user identifier ( loginData.user_identifier ) from the login form. In case of successful verification, logs in the user.
4. Depending on results, successfully completes the journey ( Complete journey step) or rejects access ( Reject access step).

Step 3: Add SDKs

To run this flow, your integration needs both the Orchestration SDK and Identity Verification SDK.

For Android, see instructions here:

• Adding to project/loading: Orchestration SDK , Identity Verification SDK
• Initializing: Orchestration SDK , Identity Verification SDK

For iOS, see instructions here:

• Adding to project/loading: Orchestration SDK , Identity Verification SDK
• Initializing: Orchestration SDK , Identity Verification SDK

Step 4: Implement journey logic

Implement the client-side code needed to execute journeys on user's device. Since face authentication is scoped per app, you have to implement face registration in each app that offers face authentication as a login method.

In a nutshell, you have to implement:

• Starting the journey. See implementation instructions below.
• Acquiring selfie. See implementation instructions below.

• Login forms with enabled password authentication and face authentication. See implementation instructions below.
• Further client logic depending on the journey completion results.

Note that Register face and Face authentication are executed by Mosaic and don't require any client-side code.

1. Start the journey

Implement a handler that starts the journey. Use the following call to start the journey by replacing YOUR_JOURNEY_ID with the journey IDs you've created in Step 2:

TSIdo.startJourney(journeyId: "YOUR_JOURNEY_ID")

TSIdo.startJourney("YOUR_JOURNEY_ID", startJourneyOptions, callback)

2. Acquire selfie

Implement a handler that collects user's selfie (using Identity Verification SDK) if the IDO service response object has the journeyStepId set to selfieAcquisition. For more details, see Selfie acquisition step guide.

For example:

private fun processServiceResponse(idoResponse: TSIdoServiceResponse) {
    when (idoResponse.journeyStepId) {
        TSIdoJourneyActionType.SelfieAcquisition.type -> handleSelfieAcquisition(idoResponse)
    }
}

private fun handleSelfieAcquisition(idoResponse: TSIdoServiceResponse) {
        var idvStartToken = idoResponse.responseData?.optString("start_token")
        idvStartToken?.let { token ->
            activity?.applicationContext?.let {
                TSIdentityVerification.initializeSDK(it)
                TSIdentityVerification.registerForStatus(object: ITSIdentityVerificationStatus{
                    ...
                    override fun verificationCompleted() {
                        TSIdo.submitClientResponse(TSIdoClientResponseOptionType.ClientInput.type, null, callback)
                    }

                    override fun verificationFail(p0: TSIdentityVerificationError) {
                        if (idoResponse.clientResponseOptions?.get(TSIdoClientResponseOptionType.Fail.type) != null) {
                            TSIdo.submitClientResponse(TSIdoClientResponseOptionType.Fail.type, null, callback)
                        } else {
                            //handle failure
                        }
                    }
                    ...
                })
                TSIdentityVerification.start(it, idvStartToken)
            }
        }
    }

class ExampleClass: TSIdentityVerificationDelegate {
    func TSIdoDidReceiveResult(_ result: Result<IdentityOrchestration.TSIdoServiceResponse, IdentityOrchestration.TSIdoJourneyError>) {
        switch result {
        case .success(let response):
            switch response.journeyStepId {
            case .selfieAcquisition:
                // Run IDV module
                guard let startToken = response.data?["start_token"] as? String else {
                    debugPrint("Start token is missing")
                    return
                }

                // Initialize IDV SDK if not initialized
                TSIdentityVerification.initialize(baseUrl: "[BASE_URL]", clientId: "[CLIENT_ID]")

                // Set delegate to receive IDV callbacks
                TSIdentityVerification.mosaicUIDelegate = self

                // Start IDV with Mosaic UI
                TSIdentityVerification.startWithMosaicUI(startToken: startToken)
            default:
                break
            }
        case .failure(let error):
            // Handle error
            break
        }
    }
}

extension ExampleClass: TSIdentityVerificationMosaicUIDelegate {
    func mosaicUIVerificationDidComplete() {
        try? TSIdo.submitClientResponse(clientResponseOptionId: .clientInput)
    }

    func mosaicUIVerificationDidCancel() {
        try? TSIdo.submitClientResponse(clientResponseOptionId: .cancel)
    }

    func mosaicUIVerificationDidFail(with error: TSIdentityVerificationError) {
        try? TSIdo.submitClientResponse(clientResponseOptionId: .fail)
    }
}

3. Display login form

Implement a handler that presents a login form with different login options if the IDO service response object has the journeyStepId set to loginForm. The form should collect input from the user depending on the branch ID returned in the clientResponseOptions. For password authentication, username and password. For face authentication, user_identifier. Then, pass the input in the submitClientResponse call to the Orchestration SDK.

For more details see Login form and Password authentication step guides.

Next steps

• Introduce step-up flows for high-risk transactions.
• Consider adding fallback methods if face authentication fails.
• Consider including the face registration into the user onboarding journey to register a face along with the user creation.