Authenticate with Face ID or Fingerprint After Initial Login
After completing initial identity verification via BankID or Vipps, the peer mentor should be prompted to enable biometric authentication for subsequent sessions. On supported devices, the app should invoke the native biometric prompt (Face ID on iOS, fingerprint or face unlock on Android) to resume an authenticated session without requiring a full re-authentication flow. This dramatically reduces the friction for high-frequency users who may register 380+ activities per year.
User Story
Audience Summaries
Biometric authentication is a MUST HAVE requirement across all four partner organizations (NHF, HLF, Blindeforbundet, Barnekreftforeningen) and represents a direct lever for solving the systemic underreporting problem that undermines each organization's operational data quality. Peer mentors at HLF alone register 380+ activities annually — forcing full BankID or Vipps re-authentication on every session creates a daily friction point that discourages consistent usage. By enabling Face ID and fingerprint login after initial verification, the product delivers near-zero friction access, directly increasing activity registration rates and improving the data accuracy that partner organizations depend on for reporting, funding justification, and program evaluation. This feature is core to the product's value proposition and a key differentiator for user retention among high-frequency users.
This critical-priority story has direct dependencies on the secure session persistence infrastructure (Story 136) and must be sequenced after it. The implementation spans iOS (Face ID via LocalAuthentication framework) and Android (BiometricPrompt API), requiring platform-specific development effort and separate device testing across supported OS versions. Acceptance criteria include six distinct scenarios covering success, fallback on three failed attempts, unsupported devices, user-initiated cancellation, and correct role-based routing post-authentication. QA must cover both OS platforms with real devices, as simulators do not fully replicate biometric behavior.
Stakeholder sign-off is needed from all four partner organizations. Rollout planning should include in-app onboarding prompts to maximize opt-in rates among existing users who may not discover the feature organically.
Implementation requires integration with Flutter's local_auth package (or equivalent native bridge) to invoke Face ID on iOS via the LocalAuthentication framework and fingerprint/face unlock on Android via BiometricPrompt. The biometric prompt must only appear after a valid persisted session token is detected in secure storage (iOS Keychain / Android Keystore). Session resumption must complete and route to the role-specific home screen within 2 seconds of successful biometric confirmation. Fallback logic must count failed attempts (max 3) and surface password or BankID/Vipps re-authentication options.
Device capability detection must gracefully skip biometric setup on unsupported hardware. Post-authentication routing must correctly resolve the user's assigned organization context and role before rendering the home screen, requiring integration with the auth state manager and role resolution service.
Acceptance Criteria
- Given I have completed initial BankID or Vipps authentication, When I open the app in a new session, Then I am presented with a biometric prompt (Face ID or fingerprint) instead of a login form
- Given biometric authentication is enabled, When I successfully authenticate with Face ID or fingerprint, Then I am taken directly to the role-based home screen within 2 seconds
- Given biometric authentication is enabled, When I fail biometric authentication 3 times, Then I am offered a fallback option to use my password or re-authenticate via BankID/Vipps
- Given I am on a device that does not support biometrics, When I complete initial login, Then biometric setup is skipped and standard session token resumption is used
- Given I have enabled biometric auth, When I tap 'Cancel' on the biometric prompt, Then I am offered the option to authenticate with password instead
- Given biometric authentication succeeds, When my session is resumed, Then I land on the correct role-specific home screen for my assigned organization context
Business Value
Biometric login is identified as a MUST HAVE for all four partner organizations (NHF, HLF, Blindeforbundet, Barnekreftforeningen). Peer mentors like those at HLF who register 380+ activities annually need near-zero friction for repeated app access. Removing password re-entry as a daily barrier directly increases activity registration rates, reducing the systemic underreporting problem all organizations currently experience. This is core to the product's value proposition.
Components
- Biometric Authentication Screen ui
- Biometric Authentication Service service
- Biometric Prompt Overlay ui
- Biometric Authentication Service service
- Session Resume Manager service
- Secure Session Storage data
- Local Auth Integration infrastructure
- Supabase Session Manager infrastructure
- Authentication Session Manager service
- Auth Token Store data
- Secure Storage Adapter infrastructure
- Role-Based Home Screen ui
- Biometric Authentication Service service