Auth Service is a self-contained authentication and authorization microservice built with Spring Boot 3 and Clean Architecture. It solves the problem of identity management for distributed systems and SPAs by centralizing account registration, email verification, JWT issuance, refresh token rotation, and OAuth2 social login in a single deployable unit. Downstream services verify the JWT using the shared secret — they never touch the auth database. Auth Service is designed for engineering teams that need a production-grade, extensible auth foundation without reinventing token lifecycle management, reuse detection, or anti-enumeration hardening from scratch.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt
Use this file to discover all available pages before exploring further.
Quickstart
Spin up Auth Service locally, register an account, and obtain your first JWT in under 5 minutes.
Architecture
Understand the Clean Architecture layers, security decisions, and token lifecycle design.
API Reference
Explore every endpoint, request schema, and response shape with live examples.
Guides
Step-by-step guides for OAuth2 setup, secret rotation, and integrating downstream services.
Key Features
- JWT Access Tokens (HS256, 15-minute TTL) — Stateless tokens signed with a 256-bit secret. Claims include
sub(account UUID),email,roles,iat,exp, andiss="auth-service". Tokens are never stored or individually revoked; expiry is their sole lifecycle boundary. - Dual-secret rotation without downtime — The service accepts a
JWT_SECRET_CURRENTandJWT_SECRET_PREVIOUSpair. Both are valid for verification during the rotation window; new tokens are only signed with the current secret. Zero-downtime key rotation is a first-class operational concern. - Opaque refresh tokens with family-based reuse detection — Refresh tokens are random opaque values. Only their SHA-256 hash is stored in the database alongside a
family_id,expires_at(7-day TTL),used_at, andrevoked_at. Presenting an already-used token triggers revocation of the entire token family, not just the replayed token. - OAuth2 social login (Google + GitHub) — Full federation flow with account linking. Accounts created via OAuth2 are immediately
ACTIVE(the provider already verified the email). A secure one-time code exchange endpoint (POST /auth/oauth2/exchange) prevents tokens from travelling in redirect URLs. - Email verification and password reset — New accounts start in
PENDING_VERIFICATIONstate. A SHA-256-hashed, single-use verification token (24-hour TTL) is sent by email. Password reset follows the same pattern with a 1-hour TTL token. - Anti-enumeration responses — Registration, resend-verification, and forgot-password all return identical response bodies regardless of whether the account exists, preventing account existence probing.
- Deny-all security by default — The
SecurityFilterChainterminates withanyRequest().authenticated(). Public paths (/auth/**,/oauth2/**,/login/oauth2/**, Swagger UI) are explicitly allowlisted inSecurityConfig. Every new endpoint is protected until declared otherwise. - RFC 9457 Problem Details — All error responses (authentication failures, domain validation errors, authorization errors) are returned as
application/problem+jsonfrom a single@RestControllerAdvice. Security-layer errors (from theJwtAuthenticationFilter) write the same format directly before reaching the MVC dispatcher.
Feature Summary
| Feature | Detail |
|---|---|
| Token format | JWT (HS256), opaque refresh token |
| Access token TTL | 15 minutes |
| Refresh token TTL | 7 days |
| Refresh token storage | SHA-256 hash only; plaintext never persisted |
| Reuse detection | Full family revocation on replayed refresh token |
| Secret rotation | Active + previous key pair; zero-downtime rotation |
| Social providers | Google (OIDC), GitHub (OAuth2) |
| Account states | PENDING_VERIFICATION, ACTIVE, LOCKED, DISABLED |
| Roles | USER, ADMIN |
| Error contract | RFC 9457 application/problem+json |
| Session strategy | Stateless (SessionCreationPolicy.STATELESS) |
| Database schema management | Flyway (versioned migrations); Hibernate validates only |
| Layer dependency enforcement | ArchUnit in CI — breaks the build on violations |
Tech Stack
| Category | Technology |
|---|---|
| Language | Java 21 |
| Framework | Spring Boot 3.4.4 (Web, Security, Data JPA, OAuth2 Client, Validation, Mail, Actuator) |
| JWT library | jjwt 0.13.0 |
| Database | PostgreSQL 15 |
| Migrations | Flyway (managed by Spring Boot BOM) |
| API documentation | springdoc-openapi 2.8.14 (Swagger UI) |
| Observability | Micrometer + OpenTelemetry (OTLP traces), Prometheus metrics |
| Resilience | Resilience4j (circuit breaker + time limiter on external calls) |
| Architecture tests | ArchUnit 1.4.2 |
| Build | Maven (./mvnw) |
| Dev dependencies | MailHog (email capture), Redpanda (Kafka-compatible broker), Docker Compose |
The password reset flow (Story 3.1) is currently in review. The endpoints
POST /auth/forgot-password and POST /auth/reset-password are deployed but may change before the story is closed. Rate limiting and brute-force lockout for these endpoints (Story 3.2) are in the backlog.