Skip to main content

ADR-005: next-auth v4 CredentialsProvider First

Status: Accepted | Date: 2026-03-13

Context​

SA3 requires authentication for staff across six permission levels (ADMIN, PRINCIPAL, VICE_PRINCIPAL, AHOD, TEACHER, TEACHING_ASSISTANT). The auth system must:

  • Authenticate with email/password on day one (admin-provisioned accounts, not self-registration)
  • Support the SA3Session shape with staffId, role assignments, department and class IDs
  • Integrate with next-auth v4 withAuth middleware
  • Be extensible to Google/Microsoft OAuth when the school confirms its SSO provider

Decision​

SA3 uses next-auth v4 with CredentialsProvider as the sole auth method at launch. Google and Microsoft OAuth are deferred. The Staff.authProvider column (LOCAL, GOOGLE, MICROSOFT) and Staff.externalId column are present from Phase 2, making OAuth a non-breaking addition.

Rationale​

  1. Local credentials suffice for a controlled provisioning flow (~150 staff).
  2. OAuth provider not confirmed -- configuring both speculatively doubles setup effort.
  3. next-auth v4 matches the workspace standard (consistent with other projects).
  4. SA3Session construction is auth-provider-agnostic -- adding OAuth only changes credential verification.
  5. Schema is forward-compatible -- authProvider and externalId ready for OAuth.
  6. NAT Gateway already provisioned for future OAuth callback flows.

Consequences​

Positive: Works on day one without school IT dependency. Consistent with workspace patterns. Password reset via SES available.

Negative: Password management overhead for admins. Staff must remember a separate SA3 password until OAuth is added.