Transition Seamlessly from Email Login to Biometric Authentication
After a successful email/password login, the app should detect whether the device supports biometric authentication and prompt the user to enable it. If accepted, future logins bypass the email/password form and authenticate using the device biometric, with the stored credentials validated against the secure session. The email/password login remains available as a fallback. This two-step onboarding (email first, biometric after) was explicitly required by all three organisations in the workshop.
User Story
Audience Summaries
Biometric authentication was explicitly requested by all three participating organisations as the primary day-to-day login method, making this story a direct delivery against confirmed stakeholder requirements rather than an exploratory enhancement. The business case is quantified and compelling: reducing login time from approximately 10 seconds (credential entry) to under 1 second (biometric scan) is transformative for field-based peer mentors who open the app frequently throughout a shift. For HLF alone, with 380 registrations per year, this time reduction compounds into measurable efficiency gains and significantly lowers the cognitive barrier to consistent data entry. Higher login convenience translates directly into more frequent and timely session recording, improving program outcome data quality and reducing the risk of retrospective — and therefore less accurate — reporting.
The two-step onboarding design (email first, biometric after) preserves security without compromising accessibility or usability for first-time users.
This high-priority story carries meaningful delivery complexity due to platform-specific biometric API surface, device capability branching, and a multi-step onboarding flow with six distinct acceptance criteria. Two upstream dependencies must be completed first: the core email/password login story and its associated secure session story. The post-login biometric prompt introduces a new UI screen that requires UX design, copy approval, and integration with both the authentication flow and the app settings module (to allow later opt-in). Delivery must account for platform-specific implementations: iOS (Face ID/Touch ID via LocalAuthentication framework) and Android (BiometricPrompt API) behave differently and require separate QA passes.
Device capability detection logic must be validated across a representative set of test devices including older hardware that may not support biometrics. The decline and fallback paths — including failed biometric recognition and device non-support — must each be covered in user acceptance testing before release.
Implementation centers on platform biometric APIs: iOS LocalAuthentication (LAContext.evaluatePolicy) and Android BiometricPrompt, typically abstracted via a cross-platform library (e.g., expo-local-authentication for React Native or equivalent). After a successful email/password login, device capability must be queried (canEvaluatePolicy / BiometricManager.canAuthenticate) before conditionally rendering the opt-in prompt. On acceptance, credentials or a session token must be stored in the device secure enclave (iOS Keychain, Android Keystore) — never in plaintext local storage. Subsequent app launches should check for a stored biometric-eligible session, display the biometric prompt if present, and fall back to the email/password form with a prescribed message on failure or cancellation.
The declined state must be persisted (e.g., a flag in secure storage or user preferences) to suppress the prompt on future sessions unless re-enabled via settings. Session resumption after successful biometric authentication must complete navigation to the home screen within the 1-second threshold defined in the acceptance criteria, requiring optimised session validation and minimal async blocking on the critical path.
Acceptance Criteria
- Given a successful first email/password login on a biometric-capable device, When the user reaches the home screen, Then a prompt appears offering to enable Face ID or fingerprint login for future sessions
- Given the user accepts biometric setup, When they next open the app with a valid stored session, Then the biometric prompt is shown instead of the login form
- Given biometric authentication succeeds, When the session is resumed, Then the user is navigated to the home screen within 1 second
- Given biometric authentication fails (e.g. unrecognised face), When the system falls back, Then the email/password login form is presented with the message 'Biometric login failed. Please sign in with your email and password.'
- Given the device does not support biometrics, When the first login completes, Then no biometric prompt is shown and the flow continues normally
- Given the user declines biometric setup, When they reopen the app later, Then the email/password form is shown without any biometric prompt unless the user enables it in settings
Business Value
All three organisations explicitly requested biometric login as the day-to-day authentication method, with email/password used only at first login. Biometric authentication reduces the time to open the app from ~10 seconds (typing credentials) to under 1 second, which is transformative for field use. For HLF's peer mentor with 380 registrations per year, this difference compounds into significant time savings and dramatically lowers the barrier to consistent reporting.
Components
- Biometric Authentication Screen ui
- Biometric Authentication Service service
- Biometric Prompt Overlay ui
- Biometric Unavailable Banner ui
- Biometric Authentication Service service
- Session Resume Manager service
- Secure Session Storage data
- Local Auth Integration infrastructure
- Biometric Authentication Service service
Dependencies
- Sign In with Email and Password critical
- Remain Logged In Across App Restarts critical