Expo Local Authentication

Common errors

• This app has not been granted the necessary permissions for Face ID.

  cause Missing `NSFaceIDUsageDescription` in `app.json`'s `infoPlist` for iOS.
  fix Add `"NSFaceIDUsageDescription": "Your app needs Face ID to authenticate you."` to `expo.ios.infoPlist` in your `app.json`.

• Biometric authentication is not available on this device.

  cause The device either lacks biometric hardware or the `expo-local-authentication` module cannot access it.
  fix Ensure `LocalAuthentication.hasHardwareAsync()` returns `true` before proceeding. If it returns `false`, gracefully inform the user.

• No biometrics enrolled on the device.

  cause The device has biometric hardware, but the user has not set up Face ID or Fingerprint authentication in their device settings.
  fix Ensure `LocalAuthentication.isEnrolledAsync()` returns `true` before attempting authentication. If it returns `false`, prompt the user to enroll biometrics in their device settings.

Warnings

• breaking On iOS, if using Face ID, you must add the `NSFaceIDUsageDescription` key to your `app.json` (under `expo.ios.infoPlist`). Without this, the app will crash when attempting to use Face ID on iOS 11 and above.
  Fix: Add `"NSFaceIDUsageDescription": "Your app needs Face ID to authenticate you."` to the `infoPlist` object within `expo.ios` in your `app.json`.
• gotcha For Android, ensure necessary permissions are declared in your `AndroidManifest.xml` (handled automatically by Expo in `app.json` for common cases). Specifically, `USE_BIOMETRIC` and `USE_FINGERPRINT`.
  Fix: Ensure your `app.json` does not override default Android permissions. If building a bare workflow app, manually add `<uses-permission android:name="android.permission.USE_BIOMETRIC"/>` and `<uses-permission android:name="android.permission.USE_FINGERPRINT"/>` to your `AndroidManifest.xml`.
• deprecated The `LocalAuthentication.supportedAuthenticationTypesAsync` method has been deprecated. It is recommended to use `LocalAuthentication.getEnrolledLevelAsync` instead to determine the strength of biometric enrollment.
  Fix: Replace `await LocalAuthentication.supportedAuthenticationTypesAsync()` with `await LocalAuthentication.getEnrolledLevelAsync()` for a more robust check on enrolled biometric types and security levels.
• gotcha It's crucial to always check `hasHardwareAsync()` and `isEnrolledAsync()` before calling `authenticateAsync()`. Failing to do so can lead to a poor user experience or unexpected errors if the device lacks hardware or the user hasn't set up biometrics.
  Fix: Implement sequential checks: `if (await LocalAuthentication.hasHardwareAsync()) { if (await LocalAuthentication.isEnrolledAsync()) { await LocalAuthentication.authenticateAsync(); } }`

Install

• npm install expo-local-authentication npm
• yarn add expo-local-authentication yarn
• pnpm add expo-local-authentication pnpm

Imports

• LocalAuthentication
  wrong:

  const LocalAuthentication = require('expo-local-authentication');

  correct:

  import * as LocalAuthentication from 'expo-local-authentication';

  This is the standard ESM import for Expo modules, bringing all functions into the `LocalAuthentication` namespace. CommonJS `require()` is generally discouraged in modern Expo/React Native projects.
• authenticateAsync

  await LocalAuthentication.authenticateAsync({ /* options */ });

  The primary method to prompt the user for biometric authentication. Accessed as a method of the `LocalAuthentication` namespace.
• hasHardwareAsync

  await LocalAuthentication.hasHardwareAsync();

  Used to check if the device supports any form of biometric authentication. Should always be checked before attempting authentication.

Quickstart

This quickstart demonstrates the full biometric authentication flow, including checking for hardware availability and user enrollment before attempting to authenticate the user. It also provides basic error handling for common authentication outcomes.

import * as LocalAuthentication from 'expo-local-authentication';
import { Alert, Platform } from 'react-native'; // Assuming a React Native environment for Alert

async function performBiometricAuth() {
  // 1. Check if biometric hardware is available
  const hasHardware = await LocalAuthentication.hasHardwareAsync();
  if (!hasHardware) {
    Alert.alert('Authentication Error', 'Biometric hardware is not available on this device.');
    return;
  }

  // 2. Check if biometrics are enrolled
  const isEnrolled = await LocalAuthentication.isEnrolledAsync();
  if (!isEnrolled) {
    Alert.alert('Authentication Error', 'No biometrics (Face ID/Fingerprint) are enrolled. Please set them up in your device settings.');
    return;
  }

  // 3. Attempt to authenticate
  try {
    const result = await LocalAuthentication.authenticateAsync({
      promptMessage: 'Authenticate to access your account',
      cancelLabel: 'Use Password', // Android specific (optional, customizes button text)
      fallbackLabel: 'Enter Passcode', // iOS specific for older versions (optional)
      disableDeviceFallback: false, // iOS specific (optional, disables passcode fallback)
    });

    if (result.success) {
      Alert.alert('Success!', 'Biometric authentication successful!');
      // Proceed with authenticated user flow
    } else {
      let errorMessage = 'Authentication failed.';
      if (result.error === 'user_cancel') {
        errorMessage = 'Authentication canceled by user.';
      } else if (result.error === 'system_cancel') {
        errorMessage = 'Authentication canceled by system (e.g., app in background).';
      } else if (result.error === 'passcode_not_set') {
        errorMessage = 'Device passcode not set, biometric authentication is not possible.';
      } else if (result.error === 'not_enrolled') {
        errorMessage = 'No biometrics enrolled on the device.';
      } else if (result.error === 'not_available') {
        errorMessage = 'Biometric hardware not available or supported.';
      }
      Alert.alert('Authentication Failed', `${errorMessage} (Error: ${result.error})`);
    }
  } catch (error) {
    console.error('Biometric authentication unexpected error:', error);
    Alert.alert('Error', 'An unexpected error occurred during authentication.');
  }
}

// To integrate this in an Expo/React Native component:
// import React from 'react';
// import { Button, View } from 'react-native';

// const BiometricAuthScreen = () => (
//   <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
//     <Button title="Authenticate with Biometrics" onPress={performBiometricAuth} />
//   </View>
// );

// export default BiometricAuthScreen;

// For immediate testing (e.g., in a standalone script or effect hook):
// (async () => {
//   if (Platform.OS === 'web') {
//     console.warn('Local authentication is not available on web.');
//     return;
//   }
//   // await performBiometricAuth();
// })();