Biometrics (iOS SDK)

Prerequisites

Before implementing authentication via biometrics, you must first integrate the Password Component into your app. This is required because:

1. Users must authenticate with their password before enrolling for biometrics. The password must be tokenised for secure communication.
2. The user must have a password or passcode set, because if biometric authentication fails (e.g. fingerprint not recognised), either password or passcode can be used as a fallback identification method.

Required components

Password component

• Required for initial authentication
• Used as the fallback authentication method (supports both password and passcode)
• Must be tokenised for security

Follow the Password Component guide to implement this in your app.

Get started

Make sure you have read the overall iOS Get started section for guidance on setting up, installing, and initialising the SDK.

The iOS SDK enables you to integrate Biometric Authentication into your iOS app. To use the iOS SDK, ensure you have obtained the necessary credentials from the Embedder Portal. Add the values in a configuration file or wherever is convenient to store securely in your app.

UI_KEY= “Your UIKey here”
API_KEY= “Your API Key here”
OWT_PROFILE_ID= ”Your OWT id here”
SEND_PROFILE_ID= “Your send profile id here”

Required capabilities

Your app target must have the push provisioning notifications capability enabled for the correct functioning of biometrics.

Implementation flows

First time only: Enrol a device

Overview

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

Initialise the SDK

To initialise both the main SDK and the Biometric Authentication component:

//initialize UX components
UXComponents.initialize(environment: .SANDBOX, uiKey: "MY-UI-KEY") { result in
    switch result {
    case .success(let status):
        print("SDK initialised!")
        print("Fixed passcode length: \(status.fixedPasscodeLength)")
        if status.userNeedsRelogin {
            // Logout the user and require a new login.
        }

    case .failure(let error):
        print("Something went wrong initialising the SDK: \(error)")
    }
}

//initialize Biometric Authentication
UXComponents.psa.initialize(psaEnv: .SANDBOX)

Push notification setup

You need to extend your push notification setup in two steps. First, you'll need to provide to the Weavr Components SDK, the device registration token:

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let fcmToken else {
        return
    }
    UXComponents.psa.updateDeviceToken(fcmToken)
}

Second, you'll need to forward to the SDK, the payload received in the push notification, so the SDK can trigger the relevant flows:

UXComponents.psa.startBiometricsChallenge(userInfo: notificationPayload) { (result) in
    print("The challenge ID: \(result.id)")
    print("The challenge type: \(result.type)")

    // Handling of the resolution state
    switch result.state {
    case .completed:
        print("Successfully completed")
    case .declined:
        print("User declined")
    case .noSessionAvailable:
        print("There is no session present")
    case .invalidPassword:
        print("The user entered an invalid password")
    case .failedToDisplay(message: let message):
        print("Failed to display the challenge: \(message)")
    case .cryptoError(message: let message):
        print("There was an error in the cryptography module: \(message)")
    case .serverError(flow: let flow, error: let error):
        print("There was a server error during the SCA flow \(flow): \(error)")
    }
}

Device enrolment

To start enrolment you must call the UXComponents.psa.startEnrollment function, passing a UIViewController to launch from, and the user's access token:

let accessToken = ""
UXComponents.psa.startEnrollment(vc: self, token: accessToken) {res in
    switch(res){
        case .success(let data):
            print(data!)
        case .failure(let err):
            print(err.message!)
    }
}

tip

You have the ability to brand this page by adjusting colours, font, and text size. You can this in the embedder portal under Settings > Authentication Config > Biometric

N.B. In the scenario where the token has changed, in your appDelegate.swift:

Biometric operations

Biometric login overview

tip

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

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

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

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")
    }
)

Check device status for enrolment

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)")
    }
}

Challenge handling

For general context about challenges, see the Step-Up Authentication and Transaction Confirmation sections of the product documentation.

The SDK automatically handles all challenge-related operations:

1. Challenge reception

   • Challenges are received through push notifications
   • The SDK expects you to pass the incoming challenges via the UXComponents.psa.startChallenge method

2. Challenge verification

   • The SDK verifies challenges using biometric authentication
   • Password or passcode fallback is automatically triggered after 3 failed attempts

3. Challenge UI

   • The SDK provides built-in UI for challenge handling
   • UI follows the branding guidelines

The component also provides information on the type of challenge that the incoming push notification refers to. WeavrChallengeType provides the following properties:

• statusMessage (String)

• challengeType (Enum), which consist of

  • case PAYMENT_INITIATION (confirming an OWT or SendSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary.)
  • case ACCOUNT_INFORMATION (stepping up a session to view account information)
  • case THREEDS_INITIATION (confirming an ecommerce transaction via 3DS)
  • case BENEFICIARY_MANAGEMENT (confirming the creation of a beneficiary)

• challengeId (string)

4. Triggering a Challenge

Challenges can be triggered by user actions from within your app, namely transaction confirmation for OWTs, SendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary., or adding a payment beneficiary; or they can be triggered by a user action outside your app, specifically using a card for an e-commerce transaction that requires 3DS approval.

Example: embedder triggered challenge

Transaction Confirmation challenges for OWTs and SendsSend A transaction type that allows sending funds to another identity's instrument or to a beneficiary. Send transactions may require Strong Customer Authentication depending on the destination and whether it's a trusted beneficiary. are triggered via the Confirmation Challenges endpoint. A challenge to verify a batch of beneficiaries can be triggered via the Beneficiaries endpoint.

Example: 3DS challenge

For the approval of an e-commerce transactions via 3DS, the challenge is triggered by an action outside of your app: a purchase by the user at an online checkout, and follows the sequence below:

Automatic fallback to password or passcode

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

1. After failed biometric attempts

   • Automatically triggered after 3 failed biometric attempts
   • No manual intervention required
   • SDK handles the entire fallback flow

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

3. Error handling

   • Handles invalid password or passcode attempts
   • Manages verification failures for both methods
   • Provides clear user feedback

Un-enrolment

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:

1. Uninstalling (and re-installing) the app.

2. By triggering a call from your backend to the multi API Unlink endpoint.