Skip to content

ADR-005: Authentication Provider

Status

Accepted — Provider TBD at Discovery

Context

Every user role (Student, Administrator, Field Coordinator) requires authenticated access. The platform handles sensitive student health data, requiring strong identity guarantees. The auth solution must support:

  • Role-Based Access Control (RBAC) with at least 4 distinct roles.
  • Single Sign-On (SSO) for school administrator accounts (linked to school email domains).
  • Multi-Factor Authentication (MFA) mandatory for Admin and Coordinator roles.
  • JWT issuance for API authentication across Flutter mobile and React admin web.
  • Self-hostable or Indian-region SaaS to meet DPDP data localisation obligations.

Options Considered

Option Type DPDP Fit RBAC MFA Cost
Keycloak Self-hosted, open-source Full control, on-prem Advanced Yes Infra cost only
Auth0 SaaS (Okta) Indian region supported Strong Yes Per-MAU pricing
Firebase Auth Google SaaS GCP asia-south1 available Limited (custom claims) Yes Free tier, then pay-per-use
Supabase Auth Open-source SaaS Self-hostable PostgreSQL RLS-backed Yes Free tier available

Decision

The final auth provider will be selected during the Discovery phase based on HarvestPlus's existing cloud agreements and any institutional SSO requirements.

Default recommendation: Supabase Auth (if Supabase is selected as the backend BaaS) or Keycloak (if self-hosted control is preferred for DPDP).

The architecture is designed to be IdP-agnostic — the backend validates JWTs via a public key; the issuer (Auth0, Keycloak, Firebase, or Supabase) is swappable without changing the API contract.

JWT & Role Structure

{
  "sub": "student-uuid",
  "role": "student",          // student | admin | coordinator | viewer
  "school_id": "school-uuid",
  "district_id": "district-uuid",
  "exp": 1234567890
}

PostgreSQL RLS policies reference the role and school_id claims directly from the JWT — enforcing data isolation at the database layer.

Consequences

Positive

  • IdP-agnostic design avoids vendor lock-in on auth infrastructure.
  • JWT claims drive PostgreSQL RLS — no application-layer access control code duplication.
  • RBAC is enforced at the database layer, not just the API layer.
  • MFA is supported by all shortlisted options.

Negative

  • Discovery must allocate time to evaluate and configure the chosen IdP.
  • Self-hosting Keycloak requires operational overhead (updates, backups, uptime monitoring).
  • Firebase Auth's RBAC via custom claims is less ergonomic than purpose-built RBAC in Keycloak/Auth0.