Biometric enrollment and login (iOS SDK)

This page covers the two ongoing operations a user performs on their device: a one-time enrollment, then biometric login on each return visit. Complete the Concepts and setup steps first - your program must be configured and the SDK initialized.

Enroll a device

Enrollment is a one-time flow that registers the user's device as an authentication factor. It runs once per user, per device.

Overview

The following sequence diagram shows the high-level flow of the biometric enrollment process:

Start enrollment

With the SDK and PSA component initialized, call UXComponents.psa.startEnrollment, passing a UIViewController to launch from:

UXComponents.psa.startEnrollment(viewController: viewController) { res in
    switch res {
    case .completed:
        print("The enrollment was completed successfully")
    case .initialisationError(error: let error):
        print("There was an error while initialising the enrollment flow: \(error)")
    case .cryptographyError(error: let error):
        print("There was an error in the cryptography operations of the enrollment flow: \(error)")
    case .failedBiometricsChallenge:
        print("The user failed the biometrics challenge")
    case .unauthorized:
        print("The token present in the SDK is not valid")
    case .userDoesNotConsent:
        print("The user cancelled the flow")
    case .failedToLoadBrand:
        print("Failed to load the brand configuration.")
    case .noPhoneNumberAvailable:
        print("No phone number available to perform the SMS OTP flow.")
    case .noBiometricsAvailable(hardwareSupportsBiometrics: let hardwareSupportsBiometrics):
        print("No biometrics available. Hardware supports biometrics: \(hardwareSupportsBiometrics)")
    case .challengeFailed(cause: let cause):
        print("The challenge failed due to \(cause)")
    }
}

tip

You can brand the enrollment screens by adjusting colors, font, and text size in the Embedder Portal under Settings > Authentication Config > Biometric.

Check device status for enrollment

UXComponents.psa.checkIsReadyForEnrollment()

Check device has been enrolled

UXComponents.psa.checkDeviceIsEnrolled { result in
    switch result {
    case .success(let isEnrolled):
        print("Is enrolled: \(isEnrolled)")
    case .failure(let error):
        print("Error: \(error)")
    }
}

tip

For first-time user-access, for a user to be fully logged in, a biometric login is required following the enrollment. Returning users should only complete a biometric login, not an enrollment every time.

The Biometrics Authentication component is designed for a single user on one device. If a different user tries to enroll, it shows as the device is already enrolled. See un-enrollment section for more details.

The following sequence diagram shows the high-level flow of a biometric login:

To implement biometric login:

UXComponents.psa.startBiometricPSALogin(completion: { res in
    switch res {
        case .success(let data):
            print("Token obtained: \(data?.token ?? "No token")")
        case .failure(let err):
            print("Error: \(err)")
        }
    }, onForgotPasscode: {
        print("Forgot passcode was called")
    }
)

Automatic fallback to password or passcode

The SDK automatically handles fallback to password or passcode authentication when biometric authentication fails:

After failed biometric attempts
- Automatically triggered after 3 failed biometric attempts
- No manual intervention required
- SDK handles the entire fallback flow
Fallback flow
- SDK automatically shows password or passcode entry screen
- Users can choose between password or passcode authentication
- Handles verification for both authentication methods
- Manages retry attempts for both options
- Provides appropriate error messages
Error handling
- Handles invalid password or passcode attempts
- Manages verification failures for both methods
- Provides clear user feedback

Un-enrollment

A device can only be enrolled to one user for Biometrics Authentication at any one time. Therefore another user cannot use the same device for Biometric Authentication in your app unless the previous user has been unenrolled. This is of particular note when testing your app with the Biometrics Authentication component, where testers may share devices.

The current user can be unenrolled by either:

Uninstalling (and re-installing) the app.
By triggering a call from your backend to the Weavr API Unlink endpoint.

Enroll a device​

Overview​

Start enrollment​

Check device status for enrollment​

Check device has been enrolled​

Biometric login​

Biometric login overview​

Automatic fallback to password or passcode​

Un-enrollment​