Face Login (iOS)

The Face Login module performs face authentication to allow users to log in without a password or token.

Supported Platforms

• iOS

How It Works

Face Login uses biometric face scanning to authenticate users without passwords or tokens. When a user initiates a login, the SDK captures a selfie and runs liveness detection to confirm the person is physically present and not a spoofed image or recording.

There are two authentication modes:

• 1:N (Identify): The captured face is compared against your entire database of approved users. The system finds the closest match and returns that user's identity. If multiple similar faces are detected, the system performs step-up authentication, prompting the user to confirm their identity with an additional code. Use this mode when you do not know in advance who is trying to log in.
• 1:1 (Verify): The captured face is compared against a single, pre-specified user identified by their customer UUID. The system returns a pass or fail for that specific person only. Use this mode when the user has already been identified by another means and you only need to confirm they are physically present.

In both modes, if liveness detection fails, the result is flagged as a spoof attempt rather than a failed face match, allowing your application to handle the two cases differently.

Prerequisites

• The user must have completed a full Incode onboarding flow and be an approved customer.

Integrate Face Login Module

Initialize the IncdOnboarding SDK

Add the following line of code to your AppDelegate class:

IncdOnboardingManager.shared.initIncdOnboarding(url: url, apiKey: apiKey)

Incode provides url and apiKey. If you are running the app on a simulator, set the testMode parameter to true.

Execute 1:N Face Login: Identify a User

Call startFaceLogin without a customerUUID to match against your full user database:

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin() { result in
          guard let loginResult = result.faceLoginResult else {
            // An error occurred
            print(result.error)
            return
          }
          
          if loginResult.success == true {
            // Face authentication successful
            let customerUUID = loginResult.customerUUID
            let token = loginResult.token
            let interviewId = loginResult.interviewId
          } else {
            if result.spoofAttempt == true {
              // Liveness check  failed
            } else {
              // No matching face found in database
            }
          }
        }

Execute 1:1 Face Login: Verify a Specific User

Call startFaceLogin with the customerUUID of the user you want to verify:

IncdOnboardingManager.shared.presentingViewController = self
IncdOnboardingManager.shared.startFaceLogin(customerUUID: "YOUR_CUSTOMER_ID") { result in
          guard let loginResult = result.faceLoginResult else {
            // An error occurred
            print(result.error)
            return
          }
          
          if loginResult.success == true {
            // Face authentication successful
            let customerUUID = loginResult.customerUUID
            let token = loginResult.token
            let interviewId = loginResult.interviewId
          } else {
            if result.spoofAttempt == true {
              // Liveness check failed
            } else {
              // User's face did not match
            }
          }
        }

View Face Login Result

The callback returns a SelfieScanResult object with the following fields:

• faceLoginResult: A FaceLoginResult object that contains:
  • success: true if face login was successful; false if it was not.
  • customerUUID: The customer UUID of the matched user; nil if no match was found.
  • token: The customer token of the matched user; nil if no match was found.
  • interviewId: The session interviewId from the user's original approval flow.
  • interviewToken: The session interviewToken used during user approval.
  • transactionId: The transaction ID of the face login attempt.
• spoofAttempt: true if the attempt was flagged as a spoof; false if it was not.
• image: The selfie image captured during the scan.
• error: A SelfieScanError describing any error that occurred.

Specify Login Parameters

By default, Face Login performs liveness detection and face matching on the server. For faster authentication and reduced network dependency, switch to on-device processing using the faceAuthMode parameter:

• To use on-device liveness detection with server-side face matching, specify FaceAuthMode.hybrid via the faceAuthMode param of the startFaceLogin method:

  IncdOnboardingManager.shared.presentingViewController = self
  IncdOnboardingManager.shared.startFaceLogin(faceAuthMode: .hybrid) { result in
            ...
          }
  

• To use on-device liveness detection and on-device face matching, specify FaceAuthMode.local via the faceAuthMode param of the startFaceLogin method:

  IncdOnboardingManager.shared.presentingViewController = self
  IncdOnboardingManager.shared.startFaceLogin(faceAuthMode: .local) { result in
            ...
          }
  

The following additional parameters are available on startFaceLogin:

Manage Locally Stored Identities

To authenticate multiple users using 1:N mode with FaceAuhtMode.local, you must populate a local database of user identities on the device. You can use the following methods to manage that database.

Add a Face

To add a single identity to the local database, use the addFace method and provide a FaceInfo object that contains the following fields:

let face = FaceInfo(faceTemplate: template,
                    customerUUID: uuid,
                    templateId: templateId)
IncdOnboardingManager.shared.addFace(face)

Remove a Face

To remove a single identity from the local database, use the removeFace method and provide a customerUUID:

IncdOnboardingManager.shared.removeFace(customerUUID: customerUUID)

Get Faces

To fetch all identities currently stored in the local database, use the getFaces method:

  var identities: [FaceInfo] = IncdOnboardingManager.shared.getFaces()

Set Multiple Faces

To replace the entire local database with a new list of identities, use the setFaces method and provide a list of FaceInfo objects:

IncdOnboardingManager.shared.setFaces(faceInfoList)

Clear the Face Database

To remove all identities from the local database, use the setFaces method and provide an empty list of FaceInfo objects:

IncdOnboardingManager.shared.setFaces([])