Authentication
Firebase Auth integration across all platforms — login, token management, route protection, and biometrics handled out of the box. You configure auth parameters and customize post-login routing.
What the Foundation Provides
| Capability | Flutter | Angular | React (Web) | React Native |
|---|---|---|---|---|
| Email/password login | ✓ | ✓ | ✓ | ✓ |
| OAuth (Google, Apple) | — | ✓ | — | — |
| Password reset / management | ✓ | ✓ | ✓ | ✓ |
| Email verification | ✓ | ✓ | — | ✓ |
| Token refresh | ✓ (automatic via Firebase) | ✓ (automatic via Firebase) | ✓ (useUserTokenRefresh) | ✓ (useIdToken) |
| Auth interceptors | ✓ (Dio interceptor) | ✓ (HTTP interceptor) | ✓ (Axios interceptor) | ✓ (Axios interceptor) |
| Route/screen protection | ✓ (navigation service) | ✓ (multi-layered guards) | ✓ (middleware) | ✓ (Stack.Protected) |
| Session timeout | — | ✓ (1hr default, 30min warning) | ✓ (inactivity monitor) | — |
| Biometric login | ✓ (Face ID / Touch ID) | — | — | ✓ (Face ID / Touch ID) |
| Secure credential storage | ✓ (FlutterSecureStorage) | — | ✓ (cookie via middleware) | ✓ (Expo SecureStore) |
| RBAC / Permissions | ✓ (sdk_access) | ✓ (access-web + Firestore) | ✓ (access-frontend-sdk) | — |
| Pre-built auth UI | — | ✓ (login, signup, password reset) | ✓ (Login, ForgotPassword, ManagePassword) | ✓ (Login, VerifyEmail, ManagePassword) |
How It Works
Token Flow
All platforms follow the same pattern: Firebase Auth issues JWTs with custom claims (roles, products, tenant). Tokens are automatically refreshed by the Firebase SDK and attached to every API request via platform-specific interceptors.
Custom claims structure:
{
appUserId: string
bootstrapTenantKey: string
customerKey: string
products: string[]
roles: string[]
email_verified: boolean
}Auth Interceptors
Every outbound HTTP request gets auth headers attached automatically:
| Header | Purpose | Platforms |
|---|---|---|
Authorization: Bearer <jwt> | API authentication | All |
X-TENANT-ID | Multi-tenant routing | All |
X-Firebase-AppCheck | Request integrity verification | Flutter, React/RN |
X-Service-Request | Opt-in token injection flag | Angular |
Flutter uses a Dio RestClientInterceptor that also checks network connectivity before every request. Two variants exist: public (allows unauthenticated) and authenticated (rejects if no user).
Angular uses HttpServiceInterceptor gated by an X-Service-Request header flag, reading tokens from localStorage.
React / RN uses Axios interceptors in the RestClient with automatic retry and tenant header injection.
Route Protection
| Platform | Mechanism | Pattern |
|---|---|---|
| Flutter | Abstract NavigationService | Module facades control screen entry; auth state drives navigation |
| Angular | Multi-layered guards | superGuard enforces: Authenticated → Terms → Email Verified → Destination |
| React (Web) | Next.js middleware | next-firebase-auth-edge validates on every server request with role-based redirects |
| React Native | Expo Router | Stack.Protected with guard={isAuthenticated} |
RBAC
Flutter and Angular both implement a product × role → permissions model backed by Firestore. The Angular implementation (@engineering11/access-web) stores permission maps in access_permission_maps/ and exposes PermissionStore, PermissionsGuard, and UseLimitService. React web provides PermissionProvider with hook-based permission checks.
What You Customize
| You Provide | Example |
|---|---|
| Auth config (URLs, tenant ID) | AuthConfig, BaseAuthConfigProvider, Firebase project IDs |
| Post-auth routing | Where to redirect after login, role-based landing pages |
| Logout cleanup | Unsubscribe Firestore listeners, clear notification tokens, reset stores |
| Permission definitions | Which permissions map to which roles for your product |
| Login screen branding | Applied via the theming system, not auth code |
Next Steps
- Theming & White-Label — How the theme system works
- Error Handling — Structured error patterns
- Platforms — Platform-specific deep dives