React Native Biometric Authentication
Typing a password on a small keyboard slows people down. Fingerprint and face recognition offer a faster, friendlier way to confirm identity. Banking apps, note vaults, and health trackers use biometrics to protect private screens. The phone performs the scan itself, and the app receives only a yes or no answer.
How It Works
App asks: "Is this the owner?"
│
▼
Operating system shows fingerprint or face prompt
│
▼
Secure hardware compares the scan to stored data
│
┌──────┴───────┐
│ │
Match No match
│ │
App unlocks App stays locked
The app never sees the fingerprint or the face data. That information stays inside secure hardware on the device.
Biometrics Confirm, Passwords Create
A biometric check proves that the person holding the phone is the registered owner. It does not replace account creation. Users still sign up with an email and password. The biometric step unlocks the saved session on later visits.
Install
npx expo install expo-local-authentication
For iOS, add a reason for Face ID in app.json.
{
"expo": {
"ios": {
"infoPlist": {
"NSFaceIDUsageDescription": "Unlock your private notes with Face ID."
}
}
}
}
Step 1: Check Device Support
Some phones lack sensors, and some users never enrolled a fingerprint or face. Check both facts before offering the feature.
import * as LocalAuthentication from 'expo-local-authentication';
const checkSupport = async () => {
const hasHardware = await LocalAuthentication.hasHardwareAsync();
const isEnrolled = await LocalAuthentication.isEnrolledAsync();
const types = await LocalAuthentication.supportedAuthenticationTypesAsync();
return { hasHardware, isEnrolled, types };
};
hasHardware isEnrolled Result ────────────────────────────────────────── false - Hide the feature true false Suggest setup in phone settings true true Offer biometric unlock
Step 2: Request Authentication
const unlock = async () => {
const result = await LocalAuthentication.authenticateAsync({
promptMessage: 'Unlock your notes',
cancelLabel: 'Cancel',
fallbackLabel: 'Use passcode',
disableDeviceFallback: false,
});
if (result.success) {
setLocked(false);
} else {
console.log('Failed because:', result.error);
}
};
With disableDeviceFallback set to false, users who fail the scan can enter the phone passcode.
Step 3: Build a Lock Screen
function LockScreen({ onUnlocked }) {
const tryUnlock = async () => {
const result = await LocalAuthentication.authenticateAsync({
promptMessage: 'Verify it is you',
});
if (result.success) onUnlocked();
};
useEffect(() => { tryUnlock(); }, []);
return (
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ fontSize: 20, marginBottom: 20 }}>Private Notes</Text>
<Button title="Unlock" onPress={tryUnlock} />
</View>
);
}
Lock on Return from Background
Apps with sensitive data should lock again when the user leaves and returns. The AppState module reports the change.
import { AppState } from 'react-native';
useEffect(() => {
const sub = AppState.addEventListener('change', (state) => {
if (state === 'background') setLocked(true);
});
return () => sub.remove();
}, []);
Protect Stored Secrets with Biometrics
Secure storage can require a scan before it returns a value.
import * as SecureStore from 'expo-secure-store';
await SecureStore.setItemAsync('token', token, {
requireAuthentication: true,
});
Reading token now triggers the biometric prompt automatically.
Handle Failures Gracefully
Error Cause Friendly Response ───────────────────────────────────────────────────── User canceled Stay on lock screen, show Unlock button Too many failures Explain the lockout, offer passcode Not enrolled Point to phone security settings Hardware missing Use password login instead
Privacy Guidelines
- Describe the feature honestly in the privacy policy
- Make biometric unlock optional, with a password alternative
- Never store or transmit biometric data
- Explain why the prompt appears
- Keep sensitive server actions protected by server-side checks
Summary
Biometric authentication gives quick, secure unlocking. Check hardware and enrollment, call authenticateAsync with a clear message, and treat the result as a simple success or failure. Add a lock on background return, offer fallbacks, and keep biometrics as a convenience layer on top of normal account security.
