Biometric enrollment and login (React Native 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:

Prepare for enrollment

Set the user token before enrolling, and make sure the FCM token is set.

Set the user token. For example:

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

setUserToken(token).then((res: any) => {
  console.log(res);
});

Then, check it has been associated correctly:

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

isAssociated().then((res) => {
  if (res) {
    // do your stuff
  } else {
    console.log("You must login first to continue!");
  }
});

Start enrollment

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

let result = await startEnrollment();

switch (result.case) {
  case "completed":
    console.log("Enrollment completed");
    break;

  case "initialisationError":
    console.log("SDK not initialised:" + result.error);
    break;

  case "cryptographyError":
    console.log("Cryptography error:" + result.error);
    break;

  case "noBiometricsAvailable":
    switch (result.biometricAvailability) {
      case "noneEnrolled":
        console.log("Device supports biometrics but none are enrolled");
        break;

      case "hwUnavailable":
        console.log("Biometrics hardware is temporarily unavailable");
        break;

      case "noHardware":
        console.log("Device has no biometrics hardware");
        break;
    }
    break;

  case "challengeFailed":
    console.log("Challenge failed:" + result.cause);
    break;

  case "failedBiometricsChallenge":
    console.log("User failed biometrics challenge");
    break;

  case "unauthorized":
    console.log("Unauthorized. Please log in again.");
    break;

  case "userDoesNotConsent":
    console.log("User did not consent to enrollment");
    break;

  case "failedToLoadBrand":
    console.log("Failed to load biometrics configuration");
    break;

  case "noPhoneNumberAvailable":
    console.log("No phone number available");
    break;
}

tip

You can brand the enrollment screens by adjusting colors, font, and text size in the Embedder Portal under Settings > Authentication Config > Biometric.

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:

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

Check device status for enrollment

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

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

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​

Prepare for enrollment​

Start enrollment​

Biometric login​

Biometric login overview​

Check device status for enrollment​

Automatic fallback to password or passcode​

Un-enrollment​