Biometric Authentication
Implementing fingerprint/face login using device hardware
GUIDE-08: Biometric Authentication Implementation Guide
Overview
This guide provides practical patterns for implementing biometric authentication (Fingerprint, Face ID) in React Native applications. It allows users to log in quickly using their device's secure hardware after an initial standard authentication.
This implementation leverages expo-local-authentication, our secureStorage wrapper (using expo-secure-store), and integrates with the core authentication flow defined in GUIDE-05.
The expected outcome is a seamless and secure secondary login method for returning users.
When To Use
Apply these patterns when:
- You want to offer users a faster way to log back in after they have successfully authenticated at least once using standard methods (e.g., email/password, social login).
- You need to securely store sensitive information (like credentials or refresh tokens) contingent on successful biometric verification.
- The target platform supports biometric hardware (most modern iOS and Android devices).
Prerequisites:
expo-local-authenticationlibrary installed (npx expo install expo-local-authentication).secureStoragehelper (usingexpo-secure-store) configured, ideally with asetSecureItemmethod that utilizes hardware security features (See DOC-04).- Core Authentication flow implemented (GUIDE-05), providing the
useAuthhook.
Alternatives:
- Password/PIN: The primary fallback mechanism.
- Magic Links / OTP: Different authentication methods altogether.
Implementation Patterns
This section details the core logic and the main hook used for biometric authentication.
Process Flow
useBiometricAuth Hook
This hook encapsulates interactions with expo-local-authentication and secureStorage.
Examples
These examples show how to integrate the useBiometricAuth hook into UI components.
Login Screen Button
Offer biometric login alongside the standard password field.
Settings Screen Toggle
Allow users to enable or disable the feature.
Common Challenges
- Credential Storage Strategy: Deciding whether to store
passwordorrefreshTokenis crucial. Refresh tokens are generally more secure if your backend supports re-authentication via refresh tokens. Storing passwords, even securely, increases risk. SecureStoreItem Invalidation: Biometric enrollment changes (adding/removing fingers/faces) or OS updates can sometimes invalidate items stored inSecureStorethat require authentication. Your logic should gracefully handle cases where stored credentials (BIOMETRIC_CREDENTIALS_KEY) cannot be retrieved, prompting the user to re-enable the feature.- Error Handling: Provide clear feedback to the user if
LocalAuthentication.authenticateAsyncfails (e.g., too many attempts, hardware error, user cancellation). - Platform Differences: While
expo-local-authenticationabstracts many differences, subtle variations in prompts or behavior might exist between iOS and Android. Test thoroughly on both. - Enabling Flow Security: The step where credentials are stored (
enableBiometricLogin) is critical. Ideally, verify the user's current password against the backend before storing it or the refresh token.
Performance Considerations
- Minimal Overhead: Biometric checks (
hasHardwareAsync,isEnrolledAsync,authenticateAsync) are generally fast native calls. - Secure Storage Speed: Reading/writing to
SecureStoreis typically quick but involves cryptographic operations. - Login Speed: The main benefit is avoiding password typing. The subsequent call to
useAuth().login(from GUIDE-05) still involves a network request, so the overall login time depends heavily on network latency and backend response time after the biometric check succeeds.
Do's and Don'ts
- (Do ✅) Prefer storing refresh tokens over passwords if possible. This minimizes the risk if the device's secure storage is compromised.
- (Do ✅) Use
secureStorage.setSecureItem(or configurerequireAuthentication: truewithSecureStore) when storing the credentials/token to bind them to successful biometric authentication. (See DOC-04). - (Do ✅) Always require explicit user consent and a successful biometric prompt before storing credentials (i.e., during the
enableBiometricLoginflow). - (Don't ❌) Automatically enable biometric login or store credentials without explicit user interaction and confirmation.
- (Do ✅) Provide a fallback to standard password login in case biometrics fail or are unavailable.
- (Consider 🤔) Requiring biometric authentication (or password confirmation) to disable the feature for added security.
- (Be Aware ❗) Of Keychain (iOS) and Keystore (Android) behavior regarding item persistence and invalidation, especially after OS updates or changes to device biometrics. Stored items might become inaccessible. (See DOC-04).
- (Do ✅) Verify user identity (e.g., re-prompt for password) before storing credentials during the
enableBiometricLoginflow, especially if storing passwords directly.
Related Documents
- GUIDE-05: Authentication Flow Implementation Guide (Core login flow)
- DOC-04: Security & Offline Framework Reference (SecureStorage details)