Biometrics - iOS
Prerequisites
Before implementing authentication via biometrics, you must first integrate the Passcode Component into your app. This is required because:
- Users must authenticate with their passcode before enrolling for biometrics. The passcode must be tokenised for secure communication.
- The user must have a passcode set, because if biometric authentication fails (e.g. fingerprint not recognised), the passcode is required as a fallback identification method.
Required components
-
Passcode Component
- Required for initial authentication
- Used as the fallback authentication method
- Must be tokenised for security
Follow the Passcode Component guide to implement this in your app.
-
Tokenisation
- Required for secure passcode handling
- Enables secure communication with backend
- Supports data matching and grouping
Learn more about Weavr Tokenisation in the Product documentation.
Get started
Make sure you have read the overall iOS Get Started section for guidance on setting up, installing, and initialising the SDK.
The Weavr iOS SDK enables you to integrate Weavr’s Biometric Authentication into your iOS app. To use the Weavr iOS SDK, ensure you have obtained the necessary credentials from the Embedder Portal. Please 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 flow
Enrolling 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.startChallenge(userInfo: notificationPayload) { (isCancelled, status, challengeType) in
print("Is flow cancelled? \(isCancelled)")
print("Status? \(status)")
print("Challenge type: \(challengeType)")
}
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!)
}
}
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 login overview
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:
-
Challenge Reception
- Challenges are received through push notifications
- The SDK expects you to pass the incoming challenges via the
UXComponents.psa.startChallenge
method
-
Challenge Verification
- The SDK verifies challenges using biometric authentication
- Passcode fallback is automatically triggered after 3 failed attempts
-
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 Send) - 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)
- case
-
challengeId
(string)
- Triggering a Challenge
Challenges can be triggered by user actions from within your app, namely transaction confirmation for OWTs, Sends, 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 Sends 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:
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:
-
Uninstalling (and re-installing) the app.
-
By triggering a call from your backend to the multi API Unlink endpoint.