Biometric Authentication Screen
Component Detail
Description
Presents the biometric prompt (Face ID or fingerprint) for returning users who have already completed BankID or Vipps first-time verification. Uses Flutter's local_auth package to trigger the OS-level biometric dialog. Falls back to PIN or re-authentication if biometrics fail.
biometric-auth-screen
Summaries
The Biometric Authentication Screen dramatically reduces friction for returning users by enabling one-touch login via Face ID or fingerprint — eliminating the need to repeat the full BankID or Vipps verification flow on every visit. This directly improves user retention and daily active engagement, as authentication becomes near-instant rather than a multi-step process. From a security standpoint, the component leverages OS-level biometric hardware, which is more tamper-resistant than password-based alternatives and reduces the risk of credential theft. By offering a seamless fallback to PIN or full re-authentication, the experience remains reliable across all device types, protecting the organization from support costs and user churn caused by authentication failures.
This component sits at medium complexity and is a critical path dependency for the returning-user authentication flow. It depends on both the biometric-auth-service and auth-session-manager, meaning those services must be stable and well-tested before UI integration begins. Development effort should account for platform divergence: Face ID (iOS) and fingerprint (Android) have different OS dialog behaviors and require separate device-lab testing. Fallback logic to PIN or full re-authentication adds branching that increases QA scope.
The local_auth Flutter package must be version-locked to avoid upstream API changes breaking the biometric prompt. Plan for regression testing cycles on both iOS and Android physical devices, as simulators do not support biometric prompts.
This component uses Flutter's local_auth package to invoke the OS-level biometric dialog, abstracting platform differences between iOS (Face ID / Touch ID via LocalAuthentication framework) and Android (BiometricPrompt API). The build(BuildContext) method renders the initial UI state, while checkBiometricAvailability() queries the device for supported modalities before triggering the prompt. On success, onBiometricSuccess() resumes the existing Supabase session via auth-session-manager without requiring a fresh token exchange. onBiometricFailure(BiometricError) handles error codes (lockout, not-enrolled, not-available) and routes to navigateToFallbackAuth() after a configurable retry threshold.
Ensure the biometric-auth-service abstracts all local_auth calls for testability via mock injection in unit tests.
Responsibilities
- Trigger OS biometric dialog via local_auth package
- Handle biometric success and resume the Supabase session
- Offer fallback to full re-authentication on repeated failure
- Display appropriate UI for Face ID vs fingerprint vs unsupported devices
Interfaces
build(BuildContext)
triggerBiometricPrompt()
onBiometricSuccess()
onBiometricFailure(BiometricError)
navigateToFallbackAuth()
checkBiometricAvailability()
Relationships
Dependencies (2)
Components this component depends on
Used Integrations (1)
External integrations and APIs this component relies on