Advanced Authentication System

Enterprise-grade Spring Boot authentication platform with JWT, MFA, session control, and observability-first operations.

Key Features

• JWT-based authentication with access/refresh token lifecycle and key rotation support
• Email verification, password reset, and secure account recovery workflows
• MFA enrollment/challenge/disable flows with temporary token support
• Session management (list sessions, revoke single session, revoke other sessions)
• Role-aware user and admin APIs (user management, status/role updates, impersonation)
• Security hardening: rate limiting, request signing, bot detection, IP reputation controls
• Auditable auth events with Prometheus metrics and Grafana-ready dashboards

Tech Stack

• Java 25
• Spring Boot 4 (Web, Security, Data JPA/JDBC, Validation, Actuator)
• PostgreSQL + Flyway migrations
• Redis (token/session and security support)
• JWT (jjwt) + Bouncy Castle cryptography
• OAuth2 client (Google), Spring Mail
• OpenAPI (springdoc-openapi)
• Maven, JUnit/Spring Test, jqwik
• Observability: Micrometer + Prometheus + Grafana
• Performance tooling: k6

Architecture Overview

[ Clients ]
    |
[ REST API Layer ]  -> auth / user / admin / security modules
    |
[ Service Layer ]   -> token, MFA, mail, session, audit, risk controls
    |
[ Data Layer ]      -> JPA/JDBC repositories
   / \
[PostgreSQL] [Redis]
    |
[ Observability ]   -> Actuator + Micrometer -> Prometheus -> Grafana

Getting Started

Prerequisites

• JDK 25
• Maven 3.9+ (or use mvnw)
• PostgreSQL and Redis (for local profile)

Setup

git clone https://github.com/Omar-Mega-Byte/Advanced-Authentication-System.git
cd "Advanced Authentication System/advanced_authentication_system"

Run (local profile)

./mvnw spring-boot:run

On Windows PowerShell:

.\mvnw.cmd spring-boot:run

Environment Variables

Core variables used across profiles:

• SPRING_PROFILES_ACTIVE (local, test, perf, prod)
• DATABASE_URL, DATABASE_USERNAME, DATABASE_PASSWORD
• REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
• JWT_SIGNING_KID, JWT_CURRENT_PRIVATE_KEY_PATH, JWT_CURRENT_PUBLIC_KEY_PATH
• PASSWORD_PEPPER, APP_AES_KEY_BASE64
• MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_ADDRESS
• GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI
• CORS_ALLOWED_ORIGINS

API Overview

Base path: /api/v1

Main auth endpoints:

• POST /auth/register
• GET /auth/verify-email
• POST /auth/login
• POST /auth/refresh
• POST /auth/logout
• POST /auth/forgot-password
• POST /auth/reset-password
• POST /auth/mfa/enrollment
• POST /auth/mfa/confirm
• POST /auth/mfa/challenge

Main user/session endpoints:

• GET /users/me
• PATCH /users/me
• PATCH /users/me/password
• GET /users/me/sessions
• DELETE /users/me/sessions/{sessionId}

Main admin endpoints:

• GET /admin/users
• PATCH /admin/users/{id}/status
• PATCH /admin/users/{id}/roles
• GET /admin/auth/logs

OpenAPI UI (default): /swagger-ui/index.html

Project Structure

• advanced_authentication_system/ - Spring Boot application source, resources, and Maven build
• docs/ - architecture, design decisions, lifecycle docs, planning artifacts
• Learning/ - onboarding and engineering learning notes
• performance/ - SQL analysis and k6 load profiles
• observability/ - Prometheus alert rules and Grafana dashboard JSON
• scripts/ - utility scripts for performance setup/seeding
• Test Results/ - security/performance/testing phase reports

Testing

Run tests from advanced_authentication_system/:

./mvnw test
./mvnw verify

Windows PowerShell:

.\mvnw.cmd test
.\mvnw.cmd verify

Deployment

• Build: ./mvnw -B clean package
• Run with prod profile and production environment variables
• Use managed PostgreSQL/Redis, externalized secrets, and TLS at ingress
• Expose Actuator metrics to Prometheus and import Grafana dashboard from observability/grafana/

Roadmap

• Add dedicated CI/CD workflow with security gates and environment promotions
• Expand anomaly/risk scoring with adaptive authentication policies
• Add API version governance and contract testing
• Harden zero-downtime key rotation and incident runbooks

License

License: Apache-2.0