Biometric authentication lets a user unlock an app with a fingerprint or a face scan instead of typing a password. It feels fast because the check happens on the device in a second. It also feels safer because the user never types a secret in front of others. Behind that simple prompt sits a careful system design. The app never sees the fingerprint image or the face template. The system checks the biometric and returns only a success or failure result. This guide shows how to implement that flow correctly.
Treat biometrics as a convenience layer over a strong account credential. A fingerprint unlocks a local key or confirms that the device owner is present. It does not replace the account password or the server session by itself. A user who changes biometrics or adds a new fingerprint may need to re-enter the account credential. That rule protects the account when a device changes hands. Design the flow so a biometric failure always leads to a safe fallback and never to an open door.
Use the system BiometricPrompt interface instead of building a custom fingerprint screen. The system prompt looks familiar to users and follows platform security rules. It also handles device differences such as fingerprint sensors and face unlock hardware. A custom prompt may look nicer but it risks leaking state or mishandling errors. The system prompt also gives consistent accessibility behaviour. Consistency matters because users trust a prompt they recognise from other apps.
val promptInfo = BiometricPrompt.PromptInfo.Builder()
.setTitle("Unlock your account")
.setSubtitle("Confirm it is you")
.setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
.build()Choose the right biometric strength
Android groups biometric methods by strength. Strong biometrics meet strict security requirements for keys and payments. Weak biometrics suit convenience unlock for low risk content. Device credential means the PIN or pattern or password that unlocks the device. Choose the strength that matches the risk of the action. A banking transfer deserves strong biometrics. A news app unlock may accept a weaker method. Asking for strong biometrics on a device that lacks them will block users who could otherwise use the app safely.
Allow device credential as a fallback when the feature allows it. A user with wet hands or a damaged sensor still needs access to the account. Device credential fallback keeps that user inside the app without weakening the flow much. The device PIN still proves possession of the device and knowledge of the secret. For high risk actions you may require biometrics alone and send the user to full account login on failure. State that rule clearly in the app so users are not surprised by a stricter path.
Check biometric availability before showing any biometric option. A device may lack hardware or the user may have enrolled nothing. Hide the biometric toggle on such devices instead of showing a button that always fails. Re-check availability when the user returns to settings because enrollment can change at any time. A settings screen that reflects the current device state feels polished and avoids dead ends.
Build the prompt flow
Start the flow from a clear user action such as tapping a sign in button or opening a protected screen. Show the system prompt with a short title and a short subtitle that names the action. A title such as Unlock your account tells the user why the prompt appeared. A subtitle such as Confirm it is you keeps the purpose clear. Avoid long explanations inside the prompt because the system dialog has limited space. Put detailed help on the app screen behind the prompt.
Handle every result callback with care. Success should unlock the local key or continue the login flow. Failure should show a short neutral message and offer a retry or a fallback. A system error such as a locked sensor should explain the wait without technical detail. A user who cancels the prompt should return to the previous screen without any partial unlock. Never treat a cancelled prompt as a soft success. Partial state after cancellation is a common source of security bugs.
Limit retry attempts in a sensible way. The system already throttles repeated biometric failures. Your app should not add a loop that reopens the prompt at once after each failure. Let the user choose to retry or choose another method. A forced retry loop frustrates users and may trigger a longer system lockout. Respect the system lockout and guide the user to device credential or account login when biometrics become unavailable.
Keys and local security
The strongest pattern ties a cryptographic key to biometric authentication. The key lives in the system keystore and requires a fresh biometric check before use. The app uses the key to decrypt a stored token or to sign a challenge. An attacker who copies app data cannot use the key without passing the biometric check on that device. This pattern is stronger than a simple boolean flag that records that biometrics once succeeded. A boolean flag can be bypassed by tampering with app state.
Create the key with user authentication required and with invalidation on new enrollment when the risk demands it. Invalidation means a newly added fingerprint disables the old key until the user re-authenticates with the account credential. That rule protects against a new fingerprint added by someone with temporary device access. For low risk apps invalidation may annoy users who add a fingerprint for a family member. Weigh the risk of the feature against the friction of re-login and document the choice.
Never store a password or a token in plain text just because biometrics gate access to the screen. Biometrics protect the entry point but the stored data still needs encryption. Use the keystore backed key for the token store. Clear the token on sign out and on biometric invalidation. Test sign out carefully because a token that survives sign out defeats the whole authentication design.
Fallback and account recovery
Design fallback before you ship biometrics. A user may lose biometric access after an injury or a sensor failure or a device repair. The fallback should be the normal account login with password and any second factor the account uses. Never offer a weak fallback such as a short PIN that bypasses the account password for sensitive actions. A fallback that is easier than the main path becomes the attack path.
Handle the case where the user disables biometrics in app settings. Disable the biometric key and clear any biometric only state at once. Do not leave a stale key that a later code path could use. Handle the case where the user removes all enrolled biometrics in system settings. The next biometric attempt should fail cleanly and guide the user to re-enroll or to use account login. Test both cases on a real device because emulators hide some enrollment behaviour.
Accessibility services and automation tools interact with authentication screens in ways that need review. A screen that auto fills or auto confirms a prompt can weaken the check. Readers who build automation features can continue with the piece on accessibility services and automation and review how those services should stay away from authentication prompts. Keep authentication screens free of auto confirmation behaviour.
Testing across devices
Test on devices with fingerprint sensors and devices with face unlock and devices with neither. Test with one enrolled fingerprint and with several enrolled fingerprints. Test after adding a new fingerprint when invalidation is enabled. Test after a device restart because some keys require a first unlock before biometric use. Record the behaviour for each case in a test matrix so regressions are easy to spot.
Test failure paths as carefully as success paths. Trigger a sensor lockout by failing repeatedly in a test build and confirm the fallback appears. Cancel the prompt at each step and confirm no screen unlocks partially. Rotate the device during the prompt and confirm the flow survives or restarts safely. Test with the app in the background during the prompt because system dialogs behave differently when the app loses focus.
Protecting app code matters alongside authentication design. An attacker who can modify the app could bypass a biometric check in a tampered build. Readers who harden the surrounding app can continue with the piece on securing source code against decompilers and treat code protection as a complement to authentication rather than a replacement for it. Authentication checks the user. Code protection raises the cost of tampering with those checks.
Ship a trustworthy biometric feature
Explain biometrics in plain language inside the app. Tell users that biometric data stays on the device and never leaves the phone for your servers. Tell users what happens when they add a new fingerprint. Tell users how to turn biometrics off. Clear explanations build trust faster than any marketing claim about security. Users who understand the model are more likely to enable the feature and less likely to fear it.
Review the feature after each major system update. Biometric APIs and strength rules evolve. A method that was strong on one version may be classified differently later. Re-run the device matrix after an update and adjust the allowed strength if needed. Keep the fallback path working even when biometrics work perfectly because the fallback is the safety net for every edge case.
Good biometric design feels invisible when it works and safe when it fails. The prompt appears at the right moment and disappears cleanly on cancel. Success opens the app without delay. Failure leads to a clear next step. Build that experience with system APIs and strong keys and honest fallback design and users will trust the feature with their daily use.
Rollout and user education
Roll out biometrics gradually when the app serves many users. Enable the feature for a small group first and watch failure rates and support tickets. A spike in lockout reports signals a strength setting that blocks too many devices. A spike in fallback use signals a prompt that confuses users. Gradual rollout catches those signals before they affect the whole audience. Expand only after the metrics look calm.
Educate users inside the app with a short setup screen. Explain that biometric data never leaves the device. Explain what happens after a new fingerprint is added. Explain how to turn the feature off. A setup screen with three short points builds more trust than a long help article that users never open. Keep the language plain and avoid security jargon that obscures the message.
Token storage deserves the same care as the biometric check itself. A token encrypted with a biometric bound key still needs a safe storage home on the device. Readers who plan token storage can continue with the piece on scoped storage and MediaStore APIs and keep token files in private storage rather than in shared media space. Private storage limits exposure if another app ever gains unexpected access.
Review biometric analytics without collecting sensitive data. Track success rates and fallback rates and device classes in aggregate. Never log biometric images or templates or raw sensor data. Aggregate metrics reveal device problems without exposing user biology. Privacy preserving analytics keep the feature trustworthy while still guiding improvements.
