All articles
Mobile DevelopmentNovember 16, 2026 6 min read

Biometric Auth in React Native 2026: Face ID, Keystore, and the Silent Logout Bug

Face ID and fingerprint login look simple until a user updates their OS and gets silently logged out. Here's how we wire biometric auth in React Native without torching trust.

Biometric login is the feature product managers underestimate and engineers over-trust. On the surface it's a two-line call to LocalAuthentication.authenticateAsync. In reality it's a contract between your app, the Secure Enclave or Android Keystore, and a user who just upgraded their OS and is now wondering why they're staring at a login screen again.

This is the article we wish we'd had the first time we shipped Face ID in a React Native app. We'll cover the Expo-friendly path, where it quietly differs from bare native, and the silent logout bug that eats session retention if you don't bind your tokens correctly.

Why biometric auth is not "login"

The single most common mistake we see in code review: treating authenticateAsync() returning success: true as proof the user is authenticated to your backend. It isn't. All it proves is that someone at the device passed the local biometric check.

The real flow has three jobs:

  1. Prove liveness/possession locally — the biometric prompt.
  2. Unlock a secret stored in hardware-backed storage (Keychain on iOS, Keystore on Android).
  3. Use that secret to authenticate against your backend, typically by decrypting a refresh token or signing a challenge.

Skip step 2 and you've built a UI gate, not a security feature. A rooted device or a determined user with ADB can bypass a pure UI check in seconds.

What Expo gives you, and what it doesn't

expo-local-authentication handles the prompt. expo-secure-store handles the hardware-backed secret. Together they cover roughly 90% of what a product app needs. What they don't give you out of the box:

  • Key invalidation on biometric enrollment changes. iOS Keychain supports this via kSecAttrAccessControl with biometryCurrentSet. Android Keystore supports it via setInvalidatedByBiometricEnrollment(true). expo-secure-store doesn't expose either directly as of SDK 52.
  • Cryptographic signing with a hardware key. For that you're looking at react-native-keychain with its lower-level APIs, or dropping to a native module.

For most apps, SecureStore plus a server-issued refresh token is enough. For banking, health records, or anything regulated, you want the signing path.

The flow we actually ship

Here's the shape we use on new projects. It assumes you already have a working email/password or SSO login that returns a refresh token.

import * as LocalAuthentication from 'expo-local-authentication';
import * as SecureStore from 'expo-secure-store';

const REFRESH_KEY = 'auth.refresh_token';

export async function enableBiometricLogin(refreshToken: string) {
  const hasHardware = await LocalAuthentication.hasHardwareAsync();
  const isEnrolled = await LocalAuthentication.isEnrolledAsync();
  if (!hasHardware || !isEnrolled) {
    throw new Error('BIOMETRICS_UNAVAILABLE');
  }

  await SecureStore.setItemAsync(REFRESH_KEY, refreshToken, {
    requireAuthentication: true,
    keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    authenticationPrompt: 'Unlock to sign in',
  });
}

export async function biometricSignIn(): Promise<string> {
  const token = await SecureStore.getItemAsync(REFRESH_KEY, {
    requireAuthentication: true,
    authenticationPrompt: 'Sign in',
  });
  if (!token) throw new Error('NO_STORED_TOKEN');
  return token;
}

A few things to notice:

  • requireAuthentication: true is what ties the SecureStore entry to the biometric prompt on retrieval. Without it, you're storing the token in plain Keychain and gating UI only.
  • WHEN_UNLOCKED_THIS_DEVICE_ONLY prevents the token from syncing via iCloud Keychain to other devices. You almost always want this for auth material.
  • We call authenticateAsync indirectly — SecureStore triggers the OS prompt itself. Calling it twice (once explicitly, then again via SecureStore) double-prompts users and is a review-flag risk.

Android's quirks

On Android, requireAuthentication: true maps to a Keystore key with setUserAuthenticationRequired(true). This has a knock-on effect: on some OEM skins (notably older Samsung and Xiaomi builds), the key gets invalidated whenever the user changes their lock screen credential, not just their biometrics. We've seen production crash reports from devices where the key simply disappeared after a security patch update.

Always wrap getItemAsync in a try/catch and treat failure as "fall back to password login," not "the app is broken."

The silent logout bug

Here's the war story. A client's app had a quiet retention cliff: every iOS point release, daily active users dipped by 4–8% for a week. Support tickets trickled in — "the app made me log in again after the update." Nothing in our logs. No crashes. No auth errors.

The cause: when a user adds or removes a Face ID enrollment (which iOS does invisibly during some OS updates that re-prompt for Face ID setup), any Keychain item tagged with biometryCurrentSet is invalidated. SecureStore with requireAuthentication: true uses a similar access control under the hood. The token is gone. The user sees a login screen. Most of them don't fill it in.

There's no clean "your key was invalidated" event. You discover it when the next read returns null or throws.

How we handle it now

Two changes made the cliff disappear:

  1. Detect invalidation early. On app launch, if the user has biometric login enabled in our own settings flag but SecureStore returns null, we show a dedicated "Re-enable Face ID" screen instead of dumping them on the generic login form. Conversion on that screen runs 3–4x higher than the standard login.
  2. Keep the refresh token's server-side lifetime longer than the Keychain entry's practical lifetime. If the device key dies but the refresh token is still valid server-side, a single password or SSO sign-in restores everything without the user having to redo 2FA.
export async function bootstrapAuth() {
  const biometricEnabled = await SecureStore.getItemAsync('auth.biometric_enabled');
  if (biometricEnabled !== 'true') return { state: 'LOGGED_OUT' };

  try {
    const token = await SecureStore.getItemAsync(REFRESH_KEY, {
      requireAuthentication: true,
    });
    if (!token) return { state: 'BIOMETRIC_INVALIDATED' };
    return { state: 'AUTHENTICATED', token };
  } catch (e) {
    return { state: 'BIOMETRIC_INVALIDATED' };
  }
}

The auth.biometric_enabled flag lives in a separate SecureStore entry without requireAuthentication, so you can always read it. It's your source of truth for user intent, independent of whether the OS still trusts your key.

App Store and Play Store landmines

A few things that have burned us or clients in review:

  • Face ID usage description. iOS requires NSFaceIDUsageDescription in Info.plist. Expo configures this via the expo-local-authentication plugin's faceIDPermission option. Forget it and the app crashes the instant a Face ID prompt would show, which reviewers will find.
  • No alternative login path. If your only way into the app is biometric, Apple reviewers have rejected builds under 2.1 and 4.0. Always offer password, passkey, or email magic link as a fallback.
  • Prompting for biometrics before login. Don't ask users to enable Face ID on first launch before they have an account. It's confusing, and reviewers flag it as misleading.
  • Android 14+ and the credential manager. Google has been nudging apps toward Credential Manager and passkeys. Biometric-only flows still pass review, but if you're building new, consider passkeys via react-native-passkey as your primary and biometrics as the unlock mechanism underneath.

Testing this properly

Simulators lie. The iOS Simulator's "Enrolled" toggle doesn't model Keychain invalidation. The Android emulator's fingerprint command doesn't model Samsung's quirks. You need real devices, and you need to test the invalidation path explicitly:

  • iOS: enroll Face ID, enable biometric login in your app, then go to Settings → Face ID & Passcode → Reset Face ID. Relaunch the app.
  • Android: enable biometric login, then go to Settings and remove the fingerprint. Relaunch.

If your app handles both gracefully with a clear re-enable path, you're probably fine. If it shows a generic login screen, you have the silent logout bug.

Where we'd start

If you're adding biometric login to an existing React Native app this quarter, do these four things in order. One: ship the expo-secure-store + requireAuthentication flow with a separate biometric_enabled intent flag. Two: build the dedicated "Re-enable biometrics" screen and instrument it — you'll learn more about your users from that screen's funnel than from any analytics dashboard. Three: extend your refresh token lifetime server-side to at least 60 days, so a Keychain wipe doesn't force a full re-authentication. Four: test the invalidation path on a real device before every major release, not just on simulators.

If you're starting a new app in 2026, skip ahead and build on passkeys with biometrics as the local unlock. The UX is better, the review story is cleaner, and you stop fighting Keychain invalidation entirely. We've written more about where we think mobile auth is heading over on the 72Technologies blog, and if you want a hand wiring any of this up, our mobile development team does this for a living.

#React Native#Expo#Security#Authentication#iOS#Android

Want a team like ours?

72Technologies builds production software for the kind of teams who actually read this blog.

Start a project