Authentication Architecture
Purpose
This document defines the authentication and authorization strategy for the Farmer1st platform.
Current State
Authentication Provider
- Choice: SuperTokens (self-hosted)
- Deployment: Running on AWS EKS alongside other services
- Scope: Authentication only (identity verification, sessions, JWT issuance)
Note: Authorization (what users can access) is handled by OpenFGA. See
08-authorization-architecture.md.
Authentication Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ PWA / │ │ Cloudflare │ │ AWS EKS │ │
│ │ Portal │ │ │ │ │ │
│ └──────┬──────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ │ 1. Login request │ │ │
│ │─────────────────────────┼──────────────────────────►│ │
│ │ │ │ │
│ │ │ ┌─────────────────┴─────┐ │
│ │ │ │ SuperTokens │ │
│ │ │ │ ┌───────────────┐ │ │
│ │ │ │ │ • Validate │ │ │
│ │ │ │ │ credentials │ │ │
│ │ │ │ │ • Issue JWT │ │ │
│ │ │ │ │ • Manage │ │ │
│ │ │ │ │ sessions │ │ │
│ │ │ │ └───────────────┘ │ │
│ │ │ └─────────────────┬─────┘ │
│ │ │ │ │
│ │ 2. JWT returned │ │ │
│ │◄────────────────────────┼───────────────────────────│ │
│ │ │ │ │
│ │ 3. API request + JWT │ │ │
│ │────────────────────────►│ │ │
│ │ │ │ │
│ │ ┌────┴────┐ │ │
│ │ │ Validate│ │ │
│ │ │ JWT │ │ │
│ │ └────┬────┘ │ │
│ │ │ │ │
│ │ │ 4. Forward if valid │ │
│ │ │──────────────────────────►│ │
│ │ │ (via Tunnel) │ │
│ │ │ │ │
│ │ 5. Response │ │ │
│ │◄────────────────────────┼───────────────────────────│ │
│ │ │ │ │
└─────────────────────────────────────────────────────────────────────────────┘
Decisions and Rationale
| Decision | Rationale |
|---|---|
| SuperTokens (self-hosted) | No per-user pricing (critical for millions of farmers), full control, customizable auth flows, open source |
| JWT tokens | Stateless validation at edge, works with Cloudflare, offline-capable for PWA |
| Edge validation (Cloudflare) | Reduce backend load, reject invalid requests early, lower latency |
Trade-offs Considered
SuperTokens vs Auth0 vs AWS Cognito
| Factor | SuperTokens | Auth0 | Cognito |
|---|---|---|---|
| Cost at scale | ✅ Self-hosted, fixed infra cost | ❌ Per-user pricing expensive | ⚠️ Cheaper but still per-user |
| Customization | ✅ Full control | ⚠️ Limited | ⚠️ Limited |
| Operational burden | ❌ Self-managed | ✅ Fully managed | ✅ Fully managed |
| Vendor lock-in | ✅ None | ❌ High | ❌ AWS-specific |
| Community/Support | ⚠️ Smaller | ✅ Large | ✅ AWS support |
Decision: At millions of farmers, per-user pricing becomes prohibitive. Self-hosting SuperTokens is the economical choice.
JWT vs Session-based Auth
| Factor | JWT | Sessions |
|---|---|---|
| Edge validation | ✅ Stateless, can validate anywhere | ❌ Requires session store lookup |
| Offline support | ✅ Token stored locally | ❌ Requires connectivity |
| Revocation | ❌ Harder (need blocklist) | ✅ Immediate |
| Scalability | ✅ No shared state | ⚠️ Session store scaling |
Decision: JWT for stateless edge validation and offline PWA support.
Authentication Methods (TBD)
Potential methods for farmer authentication:
| Method | Pros | Cons | Suitability |
|---|---|---|---|
| SMS OTP | Familiar, works on basic phones | Cost per SMS, carrier issues | ✅ High |
| WhatsApp OTP | Popular in target regions | WhatsApp dependency | ⚠️ Medium |
| Email/Password | Standard | Many farmers lack email | ❌ Low |
| Social Login | Easy onboarding | Privacy concerns, requires accounts | ⚠️ Medium |
| Biometric | Secure, easy | Device support varies | ⚠️ Future |
Security Considerations
Token Security
- Short-lived access tokens (15-30 minutes)
- Longer-lived refresh tokens (secure storage)
- Token rotation on refresh
- Secure token storage in PWA (IndexedDB encrypted or HttpOnly cookies)
Edge Validation
- Cloudflare validates JWT signature
- Checks token expiration
- Validates issuer and audience claims
- Rejects before reaching backend
Open Questions
- Which authentication methods to support for farmers?
- Token expiration times?
- How to handle offline authentication in PWA?
- Role-based access control (RBAC) structure?
- Multi-tenancy model for different stakeholders?
- Account recovery flow for farmers (often no email)?
Dependencies
- SuperTokens deployment on EKS
- Cloudflare JWT validation configuration
- PostgreSQL for SuperTokens data storage
Last Updated: 2025-12-25