Biometric login on React Native with Keychain

Adding Face ID and Touch ID to a React Native app sounds like a single API call. It isn't. There are three pieces you have to wire together: Keychain for storage, the biometric prompt for the user gate, and your auth code for what to do with the result. react-native-keychain handles the first two well. This post is about wiring all three.

I'll walk through the mental model, a storage pattern that's served me well, the configuration flags that matter, and how to deal with the prompt errors you'll see in production.

The mental model

Biometrics on mobile aren't a separate API. They're a gate on storage.

Keychain (iOS) and Keystore (Android) are key/value stores. The values live in hardware-backed secure storage on each platform. react-native-keychain exposes them with setGenericPassword and getGenericPassword. That's it.

The "biometric login" part is configuration on those two calls. When you write a value, you mark it as biometric-protected. When you read it, the OS prompts the user before handing it back. There's no separate "log in with Face ID" function. You ask Keychain for a value, and the OS decides whether to give it to you.

That's worth sitting with for a second, because it shapes everything else. The biometric prompt is a side effect of trying to read a piece of data. Once you treat it that way, the rest of the design gets a lot simpler.

The two services pattern

You'll end up with at least two namespaces, called "services" in the API. One holds your access token. The other holds a biometric-gated value that exists only to verify the user is present.

The access token namespace is unlocked. Your app reads it on every API call to attach to the Authorization header. You really don't want a Face ID prompt every time you fetch a list.

import * as Keychain from 'react-native-keychain'

await Keychain.setGenericPassword('access', accessToken, {
  service: 'access-token',
})

The biometric-gated namespace stores something the user proves they have access to. The exact value matters less than the act of retrieving it. A random per-device string works fine.

await Keychain.setGenericPassword('biometric-pass', randomValue, {
  service: 'biometric-gate',
  accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
  accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
  authenticationPrompt: { title: 'Sign in to YourApp' },
})

The flow is: read the gated value (which prompts), and on success, go ahead and use the access token. The gated value isn't the token itself. It's the proof that the current user can use the token.

The reason to keep these separate is background work. A push-notification handler that fetches data needs the access token, but it shouldn't pop a Face ID prompt when there's no UI on screen. Token in an unlocked service, biometrics on a separate service. Background reads stay quiet.

The access control flags that actually matter

Three options on setGenericPassword decide everything.

accessControl is what makes a value biometric. The two values you'll use most are BIOMETRY_CURRENT_SET on iOS and BIOMETRY_ANY on Android. They aren't quite symmetric. BIOMETRY_CURRENT_SET invalidates the value if the user adds or removes a fingerprint or face. Tighter security, more re-enrollments. BIOMETRY_ANY doesn't invalidate on enrollment changes. More convenient, less strict.

iOS gives you stricter invalidation by default. Android gives you a wider gate. BIOMETRY_CURRENT_SET on iOS is a reasonable default unless you have a reason to relax it.

accessible controls when the value is readable. A safe default is WHEN_UNLOCKED_THIS_DEVICE_ONLY. The value is readable only when the device is unlocked, and it doesn't sync via iCloud Keychain to other devices. If the user gets a new phone, they re-enroll. That's the right behavior. You don't want auth state hopping between devices on its own.

authenticationPrompt is the title shown in the OS prompt. Keep it short. The user already knows the prompt is for your app, so you don't need to repeat the app name in the title.

A note on Android string length

One Android quirk worth knowing about. The cipher used for biometric-protected values has a maximum block size, and you can hit IllegalBlockSize if the stored value is long or has characters that expand under the underlying encoding.

In practice, keeping the biometric-gated value to 30 alphanumeric characters or fewer avoids the issue:

import { Platform } from 'react-native'

const formatForKeychain = (value: string) => {
  if (Platform.OS === 'android') {
    return value.substring(0, 30).replace(/[^a-zA-Z0-9]/g, '')
  }
  return value
}

This only matters for the biometric-gated value, where the goal is presence verification, not preserving the original data. Your access token in the unlocked service can be any length.

Reading it back: the prompt and its error modes

getGenericPassword either returns the credentials or throws. The throw is where most of the work lives.

The errors come back as messages on the JS side. iOS messages are localized, so matching on the English string fails for users in other languages. The trick is to match on stable parts. Numeric error code on Android. Symbolic error name on iOS. English message as a fallback for older OS versions.

Three cases are worth telling apart:

User canceled. They tapped "Cancel" or the back button. Close the prompt quietly. No error UI, no logging as an error.

Biometric mismatch. The user's face or fingerprint wasn't recognized. Show "try again" or fall back to password. Soft failure.

Anything else. Hardware unavailable, biometric not enrolled on the device, an unexpected library state. These are the ones worth logging.

Helpers I've used:

function isBiometricUserCanceled(error: Error): boolean {
  const msg = error.message
  return (
    /code:\s*1[03][,\s]/i.test(msg) ||
    /laerrorusercanceled/i.test(msg) ||
    /user canceled the operation/i.test(msg)
  )
}

function isBiometricMismatch(error: Error): boolean {
  const msg = error.message
  return (
    /code:\s*7[,\s]/i.test(msg) ||
    /the user name or passphrase you entered is not correct/i.test(msg)
  )
}

The Android codes come from BiometricPrompt:

• 7 is ERROR_BIOMETRIC_AUTHENTICATION_FAILED (didn't recognize)
• 10 is ERROR_USER_CANCELED
• 13 is ERROR_NEGATIVE_BUTTON (the user tapped your "cancel" button)

The iOS names come from LAError. LAErrorUserCanceled is locale-independent because it's the symbol name. The English fallback in the regex catches older iOS versions where the symbol doesn't appear in the bridged error.

Match on codes first, message second, and treat anything unmatched as the "real error" bucket. That keeps your crash reporter useful. Cancels and mismatches are user actions; only the unexpected stuff needs your attention.

A few practical recommendations

A few opinions, learned the slow way.

Use the biometric-protected value only as a presence proof. Background flows need your access token without a prompt. Token in an unlocked service, biometrics on a separate service. That's what makes background work, well, work.

Keep the stored value opaque. Don't try to pack metadata into the Keychain key or value. If you need metadata about the user or session, put it in AsyncStorage keyed off the service name. Keychain values are awkward to migrate. AsyncStorage isn't.

Log biometric errors with structured tags. Operation, OS, error class. The first time biometric login breaks for a real user, you want to know which class. The second time, you want to know if it's the same class.

Test on real hardware before shipping. iOS Simulator's "Match Touch ID" menu is fine for happy paths. It doesn't reproduce the cancel and mismatch error shapes you'll see on real devices.

Closing

The pieces are simple once you separate them. Keychain is a key/value store with hardware backing. Biometrics are a gate on retrieval. Two services keep background reads from popping prompts. Pick accessControl and accessible based on how strict you want invalidation and how portable you want the value to be. Match errors on codes, not localized messages. Test on real devices.

Done right, "log in with Face ID" is a one-tap experience that keeps working when the user changes their fingerprint, switches devices, or hits a flaky network during a refresh. Most of the work isn't in the library. It's in the small decisions around it.