AuthForge

Production-ready authentication and authorization starter kit for Spring Boot 3 & Spring Security 6.

Features

Feature	Description	Status
JWT Authentication	Stateless authentication with Access Tokens & Refresh Token Rotation	Included
Two-Factor Auth (2FA)	Time-based One-Time Password (TOTP) with QR code setup	Included
OAuth2 Social Login	Single Sign-On with Google & GitHub providers	Included
Role-Based Access Control	Pre-configured `USER` and `ADMIN` roles with method security	Included
Rate Limiting	Token-bucket algorithm via Bucket4j protecting auth endpoints	Included
Feature Flags	Enable/disable features dynamically via environment variables	Included
Email Verification & Reset	HTML templates for registration verification and password reset	Included
Full-Stack Demo Dashboard	Responsive web client with Login, Register, 2FA, and Admin management	Included
Docker Compose	Pre-wired PostgreSQL, Backend, Frontend, and MailHog development environment	Included
100% Test Coverage	Comprehensive unit & integration tests with JaCoCo verification	Included

Quickstart

Prerequisites

Docker & Docker Compose

Run with Docker Compose

git clone https://github.com/FrodyGr/authforge.git
cd authforge
docker-compose up --build

Open http://localhost:4000 → Ready! 🎉

Updating containers (after code changes)

If you modify the source code, you can apply the changes by rebuilding the containers:

docker-compose down
docker-compose up --build -d

Default ports

Service	Port	URL
Frontend (Nginx)	4000	http://localhost:4000
Backend (Spring Boot)	8090	http://localhost:8090
PostgreSQL	5433	—
MailHog (Email UI)	8025	http://localhost:8025
SonarQube (separate)	9000	http://localhost:9000

🎛️ Feature Flags

Toggle features on/off via environment variables — no code changes needed.

Flag	Env Variable	Default
OAuth2 Login	`FEATURE_OAUTH2`	`true`
Two-Factor Auth	`FEATURE_2FA`	`true`
Rate Limiting	`FEATURE_RATE_LIMIT`	`true`
Email Verification	`FEATURE_EMAIL`	`true`

Active flags are exposed at GET /api/admin/features (admin only).

📧 Email Service

Uses MailHog in Docker for local email testing (no real emails sent).

Verification emails: sent on registration when FEATURE_EMAIL=true
Password reset emails: HTML emails with reset links
MailHog UI: http://localhost:8025 to view all captured emails

🧪 Tests, Coverage & SonarQube

AuthForge ensures high code quality and reliability.

Running Tests locally

cd backend
mvn clean test

JaCoCo coverage report: backend/target/site/jacoco/index.html

SonarQube Analysis

Runs in a separate Docker Compose file to keep the main stack lightweight. It enforces a Strict Quality Gate (0 Bugs, 0 Vulnerabilities, 0 Code Smells, 100% Coverage).

# Start SonarQube
docker-compose -f docker-compose.sonar.yml up -d

# Wait ~1 min for startup, then run analysis
cd backend
mvn clean verify sonar:sonar -Dsonar.host.url=http://localhost:9000 -Dsonar.login=admin -Dsonar.password=admin

Default credentials: admin / admin (change on first login).

📖 API Endpoint Guide

AuthForge uses Swagger UI (OpenAPI 3) for interactive API documentation. Once the application is running, you can explore and test all endpoints directly from your browser:

👉 http://localhost:8090/swagger-ui.html

(To use protected endpoints in Swagger, click the Authorize button and input your Bearer <accessToken>)

Below is a brief summary of the available endpoints.

1. Authentication

Endpoints for login, registration, and managing access tokens.

`POST /api/auth/register`

Creates a new account.

Access: Public

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePassword123"
}

`POST /api/auth/login`

Authenticates a user and issues JWT tokens.

Access: Public

Request Body:

{
  "email": "john@example.com",
  "password": "SecurePassword123"
}

Response: Returns an accessToken and a refreshToken. If 2FA is enabled, it returns requiresTwoFactor: true and no tokens.

`POST /api/auth/refresh`

Exchanges a valid Refresh Token for a new Access Token.

Access: Public

Request Body:

{
  "refreshToken": "your-refresh-token-here"
}

`POST /api/auth/logout`

Invalidates the current Refresh Token.

Access: Authenticated (Requires Bearer Token)

Request Body:

{
  "refreshToken": "your-refresh-token-here"
}

`POST /api/auth/forgot-password`

Initates the password reset flow by email.

Access: Public
Request Body:
```
{
  "email": "john@example.com"
}
```

`POST /api/auth/reset-password`

Resets the password using the token sent to the email.

Access: Public

Request Body:

{
  "token": "reset-token-received-via-email",
  "newPassword": "NewSecurePassword123"
}

2. Two-Factor Authentication (TOTP)

Endpoints for setting up and verifying TOTP codes.

`POST /api/2fa/setup`

Generates a TOTP secret and QR code URI for Authenticator apps.

Access: Authenticated (Requires Bearer Token)
Response: Returns secretKey and qrCodeUrl.

`POST /api/2fa/enable`

Verifies a TOTP code and activates 2FA on the account.

Access: Authenticated (Requires Bearer Token)
Request Body:
```
{
  "code": "123456"
}
```

`POST /api/2fa/disable`

Disables Two-Factor Authentication.

Access: Authenticated (Requires Bearer Token)

`POST /api/auth/2fa/verify`

Step 2 of login when 2FA is enabled. Validates code and issues JWT tokens.

Access: Public

Request Body:

{
  "email": "john@example.com",
  "code": "123456"
}

3. User Profile

Endpoints related to the logged-in user.

`GET /api/users/me`

Fetches the current user's profile information.

Access: Authenticated (Requires Bearer Token)

Response Example:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "USER",
  "emailVerified": true,
  "twoFactorEnabled": false,
  "oauth2Provider": "local"
}

4. Admin Management

Administrative actions, available only to accounts with the ADMIN role.

`GET /api/admin/users`

Fetches a list of all registered users.

Access: ADMIN Only

`PUT /api/admin/users/{id}/role`

Changes the role of a user.

Access: ADMIN Only
Path Parameter: id - The numeric ID of the user.
Request Example: ?role=ADMIN (as Request Parameter)

`GET /api/admin/features`

Fetches the active states of system feature flags.

Access: ADMIN Only

🏗️ Architecture

┌─────────────────────────────────────────────┐
│                Docker Compose               │
├──────────┬──────────────┬───────────────────┤
│ Frontend │   Backend    │    PostgreSQL     │
│ Nginx    │ Spring Boot  │                   │
│ :4000    │ :8090        │    :5433          │
│          │              │                   │
│ HTML/CSS │ Controllers  │  users table      │
│ JS       │ Services     │  refresh_tokens   │
│          │ Security     │                   │
│  /api/* ──►  JWT Filter │                   │
│          │  BCrypt      │                   │
└──────────┴──────────────┴───────────────────┘

⚙️ Configuration

All configuration is done via environment variables (see .env.example):

Variable	Default	Description
`DB_URL`	`jdbc:postgresql://postgres:5432/authforge`	Database URL
`DB_USERNAME`	`authforge`	Database user
`DB_PASSWORD`	`authforge`	Database password
`JWT_SECRET`	(change me!)	HMAC-SHA256 signing key
`CORS_ORIGINS`	`http://localhost:4000`	Allowed CORS origins
`GOOGLE_CLIENT_ID`	—	Google OAuth2 Client ID
`GOOGLE_CLIENT_SECRET`	—	Google OAuth2 Client Secret
`GITHUB_CLIENT_ID`	—	GitHub OAuth2 Client ID
`GITHUB_CLIENT_SECRET`	—	GitHub OAuth2 Client Secret
`OAUTH2_REDIRECT_URI`	`http://localhost:4000`	Frontend redirect after OAuth2

🔑 OAuth2 Setup (Google & GitHub)

Google

Go to Google Cloud Console → APIs & Services → Credentials
Create an OAuth 2.0 Client ID (Web Application)
Set Authorized redirect URI: http://localhost:8090/login/oauth2/code/google
Copy the Client ID and Client Secret into your .env file

GitHub

Go to GitHub Settings → OAuth Apps → New OAuth App
Set Authorization callback URL: http://localhost:8090/login/oauth2/code/github
Copy the Client ID and Client Secret into your .env file

⏱️ Rate Limiting

Auth endpoints (/api/auth/**) are rate-limited to prevent brute-force attacks.

Setting	Default	Env Variable
Requests per minute (per IP)	30	`RATE_LIMIT_RPM`

When the limit is exceeded, the API returns HTTP 429 Too Many Requests.

📋 Roadmap

v1.0 — JWT Auth, Roles, Password Recovery, Docker
v1.1 — OAuth2 (Google, GitHub)
v1.2 — 2FA (TOTP), Rate Limiting
v2.0 — Email Service, Account Verification, Feature Flags, 100% Coverage, 0 SonarQube issues

Complete API Reference

For a complete catalog of all REST endpoints, request/response DTOs, environment variables, and feature flags, see the Complete API Reference Guide.

License

MIT — Use this starter kit freely in your projects.

Java 21 • Spring Boot 3 • Spring Security 6
by Carlos Expósito

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
docs		docs
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.sonar.yml		docker-compose.sonar.yml
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

AuthForge

Features

Quickstart

Prerequisites

Run with Docker Compose

Updating containers (after code changes)

Default ports

🎛️ Feature Flags

📧 Email Service

🧪 Tests, Coverage & SonarQube

Running Tests locally

SonarQube Analysis

📖 API Endpoint Guide

1. Authentication

POST /api/auth/register

POST /api/auth/login

POST /api/auth/refresh

POST /api/auth/logout

POST /api/auth/forgot-password

POST /api/auth/reset-password

2. Two-Factor Authentication (TOTP)

POST /api/2fa/setup

POST /api/2fa/enable

POST /api/2fa/disable

POST /api/auth/2fa/verify

3. User Profile

GET /api/users/me

4. Admin Management

GET /api/admin/users

PUT /api/admin/users/{id}/role

GET /api/admin/features

🏗️ Architecture

⚙️ Configuration

🔑 OAuth2 Setup (Google & GitHub)

Google

GitHub

⏱️ Rate Limiting

📋 Roadmap

Complete API Reference

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`POST /api/auth/register`

`POST /api/auth/login`

`POST /api/auth/refresh`

`POST /api/auth/logout`

`POST /api/auth/forgot-password`

`POST /api/auth/reset-password`

`POST /api/2fa/setup`

`POST /api/2fa/enable`

`POST /api/2fa/disable`

`POST /api/auth/2fa/verify`

`GET /api/users/me`

`GET /api/admin/users`

`PUT /api/admin/users/{id}/role`

`GET /api/admin/features`