Biometrics - React Native

Prerequisites

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

1. Users must authenticate with their passcode before enrolling for biometrics. The passcode must be tokenised for secure communication.
2. 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

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

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

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 login overview

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 {
            setGlobalToken(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.