Biometrics - React Native

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 set, because if biometric authentication fails (e.g. fingerprint not recognised), the password is required as a fallback identification method.

Required components

1. Password component

   • Required for initial authentication
   • Used as the fallback authentication method
   • 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 React Native Get Started section for guidance on setting up, installing, and initializing the SDK.

The Weavr React Native SDK enables you to integrate Weavr’s Biometric Authentication into your React Native app. To use the Weavr React Native 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 UI key goes here";
API_KEY = "Your API key goes here";
OWT_PROFILE_ID = "Your profile id goes here";
SEND_PROFILE_ID = "Your send profile ";

Push notification setup

Android setup

1. Notification Channel

   • The SDK automatically creates a notification channel with ID "Weavr-auth-channel"
   • Channel is configured with high importance for authentication notifications
   • Vibration and lights are enabled by default

2. Permissions

   import { PermissionsAndroid } from "react-native";
   
   async function requestUserPermission() {
     // Request notification permission for Android 13+
     if (Platform.OS === "android") {
       await PermissionsAndroid.request(
         PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
       );
     }
   }

iOS setup

1. Background Modes

   • Add the following to your app.config.ts:

   ios: {
     infoPlist: {
       UIBackgroundModes: ['fetch', 'remote-notification'],
     },
     entitlements: {
       'aps-environment': 'production',
     },
   }

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:

import {
  initializeUXComponents,
  initializePSA,
} from "@weavr-io/secure-components-react-native";

initializeUXComponents(env, WEAVR_UI_KEY)
  .then((res) => console.log(res))
  .catch((e) => console.log(e));

//if you are using biometric solution
initializePSA(env)
  .then((res) => console.log(res))
  .catch((e) => console.log(e));

Device enrolment

To start enrolment:

import {startEnrollment} from "@weavr-io/secure-components-react-native";

startEnrollment(fcmToken!, userAccessToken!)
  .then((res) => {
    console.log(res);
    Toast.show(res, 1);
  })
  .catch((e) => {
    console.log(e);
    Toast.show(e.toString(), 1);
  });

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

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 will show 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:

import { startBiometricLogin } from "@weavr-io/secure-components-react-native";

startBiometricLogin()
  .then((res) => {
    const { error, result } = res;
    if (error) {
      Toast.show("Error: " + error.message, 1);
    } else {
      // get token from result.token
    }
  })
  .catch((e) => {
    console.log(e);
  });

Update FCM token (iOS only)

Call the following function every time you get a new FCM token. Please make sure you have enabled it for iOS only, or it causes a non-support issue on Android.

import { updateFCMToken } from "@weavr-io/secure-components-react-native";

const token = await messaging().getToken();

updateFCMToken(token)
  .then((res) => console.log("token updated"))
  .catch((e) => console.log(e));

Check device status for enrolment

import { checkDeviceIsEnrolled } from "@weavr-io/secure-components-react-native";

checkDeviceIsEnrolled()
  .then((res) => {
    //do your stuff here
  })
  .catch((e) => console.log("Not enrolled"));

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 automatically processes incoming challenges

2. Challenge verification

   • The SDK verifies challenges using biometric authentication
   • 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

4. 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:

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

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