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(traceability: let traceability):
        print("The enrollment was completed successfully")
    case .initialisationError(error: let error, traceability: let traceability):
        print("There was an error while initialising the enrollment flow: \(error)")
    case .cryptographyError(error: let error, traceability: let traceability):
        print("There was an error in the cryptography operations of the enrollment flow: \(error)")
    case .failedBiometricsChallenge(traceability: let traceability):
        print("The user failed the biometrics challenge")
    case .unauthorized(traceability: let traceability):
        print("The token present in the SDK is not valid")
    case .userDoesNotConsent(traceability: let traceability):
        print("The user cancelled the flow")
    case .failedToLoadBrand(traceability: let traceability):
        print("Failed to load the brand configuration.")
    case .noPhoneNumberAvailable(traceability: let traceability):
        print("No phone number available to perform the SMS OTP flow.")
    case .noBiometricsAvailable(hardwareSupportsBiometrics: let hardwareSupportsBiometrics, traceability: let traceability):
        print("No biometrics available. Hardware supports biometrics: \(hardwareSupportsBiometrics)")
    case .challengeFailed(cause: let cause, traceability: let traceability):
        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

let isEnrolled = UXComponents.psa.isEnrolled()

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, call startBiometricLogin(viewController:), passing a UIViewController to launch from:

let result = await UXComponents.psa.startBiometricLogin(viewController: viewController)
switch result {
case .success(let loginData, let traceability):
    print("Token obtained: \(loginData.token)")
case .userEnteredInvalidFallbackPassword(let code, let message, let traceability):
    // The user's fallback password (used when biometrics fail or are unavailable) was
    // wrong. Surface `message` inline and let them retry; `code` can reflect a lockout
    // after too many attempts, in which case fall back to standard password login.
case .userDeclinedChallenge(let traceability):
    // The user cancelled the OS biometric prompt. This isn't an error - dismiss the flow
    // quietly and let them use standard login instead.
case .cryptoError(let error, let message, let status, let traceability):
    // The device's local key material is broken or missing, e.g. after a device restore.
    // The user needs to re-enroll biometrics; prompt the enrollment flow again.
case .serverError(let code, let message, let traceability):
    // The server rejected the request. Show a generic error and let the user retry.
case .networkFailure(let cause, let traceability):
    // The device couldn't reach the server. Retry once connectivity is restored.
case .failure(let cause, let traceability):
    // An unexpected error occurred. Retry, and share `traceability` with our
    // support team if it keeps happening.
}

The "Forgot passcode" flow is presented as part of the viewController-driven flow, so it no longer needs a separate callback.

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​