Skip to content

Latest commit

 

History

History
149 lines (123 loc) · 4.14 KB

PHASES.md

File metadata and controls

149 lines (123 loc) · 4.14 KB

Secure Authentication Service

Modern, production-ready authentication backend with progressive hardening + clean React frontend integration.

Project Phases & Milestones

Phase 1 — Core Backend (Must-have)

Goal: Password-based authentication implemented correctly and securely

  • Spring Boot 3.x project setup
  • Dependencies: Spring Web, Spring Security, Spring Data JPA
  • Database: MySQL
  • Cache & token store: Redis
  • Core domain entities
    • User
    • Role (USER, ADMIN, …)
    • RefreshToken
    • LoginAudit
  • Password handling
    • BCrypt strong hashing
  • Classic flows
    • Register → Login
  • Token strategy
    • Short-lived Access JWT
    • Long-lived Refresh JWT (stored in Redis + httpOnly cookie)
  • Security architecture
    • Stateless JWT filters
    • Cookie-based token transport (httpOnly + secure + sameSite)
    • Role-based authorization (USER / ADMIN)
    • @PreAuthorize method security

Phase 2 — Auth Hardening

Goal: Real-world account protection & abuse prevention

  • OTP module
    • Login OTP (email first, SMS abstraction prepared)
    • Passwordless login (magic link / OTP) - (currently support OTP)
    • One-Time Token (OTT) pattern
    • Expiry enforcement + Redis storage
  • Account protection mechanisms
    • Failed login tracking per user + IP
    • Temporary account lock after threshold
    • Progressive delay / CAPTCHA trigger (future)

Phase 3 — OAuth & Extensibility

Goal: Enterprise-grade login options & future-proof structure

  • OAuth 2.0 Authorization Code + PKCE
    • Google provider implemented first
  • Account linking / merging logic
  • Consistent internal JWT issuance → even OAuth/social logins receive internal JWT
  • Passkey / WebAuthn foundation
    • Database structure prepared
    • Feature flag only (no UI in this phase)

Phase 4 — Reliability & Observability

Goal: Production confidence & monitoring

  • Rate limiting (Redis-backed)
    • Login endpoint
    • OTP resend
  • Resilience4j
    • RateLimiter on expensive external calls
    • CircuitBreaker for OTP provider & OAuth providers
  • Authentication analytics
    • Login success / failure events
    • Registration source tracking
  • Admin APIs
    • Basic admin dashboard endpoints
  • API Documentation
    • OpenAPI 3 / Swagger UI
    • Secured documentation access
    • Role-based visibility of endpoints

Phase 5 — Frontend (React)

Goal: Clean, type-safe authentication experience

  • React 18 + TypeScript
  • Auth architecture
    • Axios instance with interceptors
    • httpOnly cookie-based auth (no localStorage JWT)
    • Protected routes / role-based route guards
  • Main screens
    • Login (password + OTP option)
    • Register
    • OTP verification
    • Admin dashboard (basic)
  • UI stack
    • shadcn/ui components
    • React Hook Form + Zod validation
  • Analytics integration
    • Authentication event tracking hooks

Phase 6 — Final Production Touch

Goal: Reusable, configurable auth service

  • Config-driven authentication methods
    • Enable/disable OTP
    • Enable/disable OAuth providers
    • Enable/disable password login
  • Multi-client / multi-tenant readiness
    • Client ID validation
    • Allowed redirect URIs control
  • Documentation
    • Integration guide for new frontend clients
    • Environment variables reference
  • Security hardening
    • Proper CORS configuration
    • CSRF protection (double-submit cookie pattern when using cookies)
    • Refresh token rotation strategy

Tech Stack (Planned)

Backend

  • Java 21 • Spring Boot 3.x
  • Spring Security + JWT
  • MySQL 8.x
  • Redis 7.x
  • Resilience4j
  • Lombok, MapStruct
  • Docker

Frontend

  • React 18 + TypeScript
  • Vite
  • Axios
  • shadcn/ui + Tailwind CSS
  • React Router v6
  • Zod + React Hook Form

Security Design Principles

  • Never store JWTs in localStorage / sessionStorage
  • httpOnly + Secure + SameSite=Strict/Lax cookies
  • Short-lived access tokens + refresh token rotation
  • Least privilege by default
  • Rate-limit everything that can be abused
  • Prepare for passkeys / WebAuthn from day one
  • Internal JWT even for OAuth logins (unified auth)

Work in progress — follow the phase order for best incremental security posture.