Biometric enable in Expo apps ships when every fallback is handled

Biometric authentication, such as Face ID on iOS or fingerprint recognition on Android, can enhance the user experience in mobile apps by streamlining the sign-in process. However, integrating biometrics into an Expo app requires careful consideration of several factors.

First, it's essential to check a device's capabilities at runtime. Not every device supports biometrics, and even among those that do, some users may not have enrolled any biometric data. The `expo-local-authentication` module provides methods to detect hardware support, check enrollment status, and retrieve supported authentication types.

Based on these checks, the app should present an appropriate user interface. For devices without biometric hardware, there's no need to display a biometric toggle. If a device has hardware but no enrolled biometrics, the app should offer the option to enroll and provide instructions on how to do so. It's crucial to use the `supportedAuthenticationTypesAsync` method to determine the specific biometric technology (facial recognition, fingerprint, iris scanning) and adjust the UI language accordingly.

When it comes to user consent, biometrics should never be enabled without explicit user approval. After a successful password or single sign-on (SSO) sign-in, the app should present an opt-in screen asking, "Enable faster next time with Face ID?" This screen should include equal-weight options for allowing or skipping the biometric feature.

The user's choice should be securely stored, such as in the keychain or keystore, to ensure it's not accidentally altered. To maintain security, the opt-in flag should be kept separate from sensitive data like refresh tokens, which should also be stored securely.

When implementing biometric authentication, it's important to provide a clear fallback path. The `authenticate` method should be called with appropriate parameters, such as a prompt message and a cancel label for cases where users might switch to a password or PIN. If biometrics fail repeatedly, the operating system may automatically fall back to a device PIN or passcode, ensuring the user remains unblocked.

It's crucial to handle various failure scenarios, such as user cancellation, system cancellation (e.g., an incoming call), and lockout after too many attempts. Each failure case should be logged as a distinct analytics event to help identify areas for improvement in the prompt timing or copy.

Another common mistake is storing the user's password behind the biometric check. This approach undermines the security benefits of biometrics and increases the risk of breaches. Instead, a token-based approach should be used. After the initial full sign-in, a refresh token should be securely stored and protected by the biometric authentication.

Access to this token should only be granted after a successful biometric check. When implementing session refresh, this token should be used as a pre-step before the normal refresh call. Additionally, session hygiene is crucial; expired or revoked sessions should trigger a full sign-in process rather than looping on a dead token.

Biometrics are tied to the current enrollment status on the device. If a user adds or removes a fingerprint, iOS may invalidate keychain items protected by biometrics, and Android may change the cryptographic key. Therefore, the app must be prepared to handle changes in biometric enrollment. This could involve prompting the user to re-enroll or providing clear instructions on how to do so.