Face authentication

Face authentication is a next-generation biometric authenticator that combines speed, security, and user convenience. By leveraging Mosaic 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.
Note

This guide explains how to implement face authentication using Journeys and Mosaic SDKs.

Important

This authentication is currently only available for mobile apps.

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, 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 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.

UserClientIDO SDKIDV SDKMosaicJourney runs...collects external user ID/logs in the userRegister my faceStart registration journeySelfie acquisition step (with start_token)Init SDK (with start_token)Obtain selfie (Mosaic UI)SelfieCompleteselfie_dataRegister face for userDoneJourney completeYou've registered your faceUserClientIDO SDKIDV SDKMosaic

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.

UserClientIDO SDKIDV SDKMosaicJourney runs...collects user identifierLog me inStart auth journeySelfie acquisition step (with start_token)Init SDK (with start_token)Obtain selfie (Mosaic UI)SelfieCompleteselfie_dataAuthenticate faceSuccess (user authenticated)Journey completeLogged inUserClientIDO SDKIDV SDKMosaic

Requirements

iOS:

  • iOS 13+
  • Xcode 11+

Android:

  • Android 5+ (API level 21+)

Before you start

Admin Portal

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

Admin Portal

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.
Tip

Once you've configured the lockout policy, you may also implement logic to unlock the authenticator in case it locks. Use the Unlock authenticators API to reset a locked authenticator.

For more about this authenticator, see Customize login methods.

Step 2: Build journeys

Admin Portal

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).
Register face flow example
Click to open the image in a dedicated tab.

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).
Face auth flow example
Click to open the image in a dedicated tab.

Step 3: Add SDKs

client

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

Important

Make sure to initialize mobile SDKs within the context of the same client ID and the same region.

For Android, see instructions here:

For iOS, see instructions here:

Step 4: Implement journey logic

client

Implement the client-side code needed to execute journeys on user's device.

In a nutshell, you have to implement:

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

Implementation tips

For example, implement a switch (or other routing mechanism) that invokes a handler responsible for a specific journey step (returned in idoServiceResponse.journeyStepId parameter). Each handler processes data, displays whatever UI is needed, and calls submitClientResponse() when the interaction is concluded.

The journey loops back to the switch unless Mosaic signals journey completion by setting the journeyStepId property to Rejection.type or Success.type. The idoServiceResponse.token property contains a JWT token as a proof of journey completion.

For more guidance on mobile development with the Orchestration SDK, refer to these quickstarts: Android or iOS as well as individual step guides.

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:

swiftkotlin
Copy
Copied
TSIdo.startJourney(journeyId: "YOUR_JOURNEY_ID")
Copy
Copied
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:

kotlinswift
Copy
Copied
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)
            }
        }
    }
Copy
Copied
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.