🔐 Spring User Management API

Secure & Production-Oriented REST API for User Management

---

📌 Overview

Spring User Management API is a secure, production-oriented REST API for user management built with Java 21 and Spring Boot 4.1.0.

The API provides:

• 🔐 JWT authentication with Access & Refresh Tokens
• 👥 Role-based authorization
• 📄 Pagination & filtering
• 📚 OpenAPI / Swagger documentation
• 🐘 PostgreSQL database
• 🗃️ Flyway database migrations
• 🐳 Docker & Docker Compose
• 🧪 Unit, security & integration testing
• ⚙️ GitHub Actions CI
• 🔍 Qodana code quality analysis

The project follows a layered architecture and focuses on security, maintainability, testing, and clean separation of responsibilities.

---

✨ Features

🔐 Authentication

• User registration
• User login
• JWT Access Token
• JWT Refresh Token
• Refresh token persistence
• Current authenticated user endpoint

👤 User Management

• Get current user
• List users
• Pagination
• Email filtering
• User deletion
• Admin-only user management

🛡️ Authorization

Two roles are available:

USER
ADMIN

USER provides standard authenticated access, while ADMIN provides elevated access to administrative endpoints.

🧯 Error Handling

• Global exception handling
• Custom exceptions
• Validation error responses
• Appropriate HTTP status codes

📖 API Documentation

The project includes:

• OpenAPI
• Swagger UI
• OpenAPI JSON specification

❤️ Health & Monitoring

Spring Boot Actuator provides application health checks.

---

🧰 Tech Stack

Technology	Purpose
☕ Java 21	Programming language
🍃 Spring Boot 4.1.0	Application framework
🔐 Spring Security	Authentication & authorization
🗄️ Spring Data JPA	Data access
🐘 PostgreSQL 16	Relational database
🗃️ Flyway	Database migrations
🎫 JJWT 0.12.6	JWT authentication
✅ Jakarta Bean Validation	Request validation
📚 springdoc-openapi	OpenAPI / Swagger
❤️ Spring Boot Actuator	Health & monitoring
🧩 Lombok	Boilerplate reduction
📦 Maven	Build tool
🧪 JUnit 5	Unit testing
🧪 Mockito	Mock-based testing
🌐 MockMvc	Controller & security testing
🐳 Docker	Containerization
🔄 Docker Compose	Multi-container environment
⚙️ GitHub Actions	CI
🔍 Qodana	Static code analysis

---

🏗️ Architecture

The application follows a classic layered architecture:

                         ┌─────────────────────┐
                         │       Client        │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │     Controller      │
                         │   REST Endpoints    │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │      Service        │
                         │   Business Logic    │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │     Repository      │
                         │    Spring Data JPA  │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │    PostgreSQL DB    │
                         └─────────────────────┘

Layers

Layer	Responsibility
Controller	HTTP request & response handling
Service	Business logic
Repository	Database access
Entity	JPA entities
DTO	Request & response models
Security	JWT & authentication
Exception	Centralized error handling
Migration	Flyway database migrations
Config	Application configuration

Package root:

com.example.usermanagement

---

🔐 Authentication & Authorization

Authentication is implemented using JWT.

Token Lifecycle

Token	Lifetime	Storage
🔑 Access Token	15 minutes	Stateless JWT
♻️ Refresh Token	7 days	PostgreSQL

Protected endpoints require:

Authorization: Bearer <access_token>

Access Flow

┌──────────┐
│  Login   │
└────┬─────┘
     │
     ▼
┌──────────────────┐
│ Access + Refresh │
│     Tokens       │
└────┬─────────────┘
     │
     ▼
┌──────────────────┐
│ Protected API    │
│ Bearer Token     │
└────┬─────────────┘
     │
     ▼
┌──────────────────┐
│   JWT Filter     │
└────┬─────────────┘
     │
     ▼
┌──────────────────┐
│ Spring Security  │
└──────────────────┘

---

👥 Roles

USER

Standard authenticated access.

ADMIN

Elevated privileges including:

• Admin user listing
• User deletion
• Admin dashboard

Role-based access is enforced at the endpoint level through Spring Security.

---

📡 API Endpoints

Method	Endpoint	Authentication	Description
POST	/api/auth/register	🌐 Public	Register a new user
POST	/api/auth/login	🌐 Public	Authenticate and receive tokens
POST	/api/auth/refresh	🌐 Public	Get a new access token
GET	/api/users/me	🔐 User	Get current user
GET	/api/users	🔐 User	Paginated user listing
GET	/api/users/admin	👑 Admin	Admin user listing
DELETE	/api/users/{id}	👑 Admin	Delete user
GET	/api/admin/dashboard	👑 Admin	Admin dashboard
GET	/actuator/health	🌐 Public	Health check

---

🚀 API Usage

The examples below use HTTPie.

Register

http POST :8080/api/auth/register \
  email=jolia@example.com \
  password=password123 \
  firstName=Jolia \
  lastName=Example

Login

http POST :8080/api/auth/login \
  email=jolia@example.com \
  password=password123

Refresh Token

http POST :8080/api/auth/refresh \
  refreshToken="YOUR_REFRESH_TOKEN"

Current User

http GET :8080/api/users/me \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Users

http GET :8080/api/users \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

Admin Dashboard

http GET :8080/api/admin/dashboard \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

Delete User

http DELETE :8080/api/users/1 \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

📄 Pagination & Filtering

The user listing supports pagination and optional email filtering.

Pagination

http GET ":8080/api/users?page=0&size=10" \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

Email Filtering

http GET ":8080/api/users?email=jolia@example.com" \
  "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

🧯 Error Handling

The API provides centralized error handling through:

GlobalExceptionHandler

Custom exceptions include:

UserAlreadyExistsException
UserNotFoundException

Validation errors are returned in a consistent structure with appropriate HTTP status codes.

---

🧪 Testing

The project includes several levels of testing.

Unit Tests

AuthServiceTest
UserServiceTest

Controller Security Tests

AuthControllerTest
UserControllerSecurityTest
UserAdminControllerSecurityTest
AdminControllerSecurityTest

Integration Tests

AuthUserIntegrationTest

Application Context

The project also includes an application context test.

Run Tests

./mvnw clean test

---

🐳 Docker

The application and PostgreSQL database can be started together using Docker Compose.

docker compose up -d

Services

Service	Address
🚀 API	localhost:8080
🐘 PostgreSQL	localhost:5432

Inside the Docker network, the application connects to PostgreSQL through:

postgres

---

📚 API Documentation

Once the application is running:

Swagger UI

http://localhost:8080/swagger-ui/index.html

OpenAPI JSON

http://localhost:8080/v3/api-docs

---

❤️ Health Check

Check application health:

curl http://localhost:8080/actuator/health

Expected response:

{
  "status": "UP"
}

---

⚙️ CI/CD

The repository includes GitHub Actions workflows.

Workflow	Purpose
ci.yml	Run tests on every push and pull request
qodana_code_quality.yml	Static code analysis with Qodana

---

📁 Project Structure

src/main/java/com/example/usermanagement
│
├── config/
│   ├── JpaConfig.java
│   └── OpenApiConfig.java
│
├── controller/
│   ├── admin/
│   ├── auth/
│   └── user/
│
├── dto/
│   ├── auth/
│   ├── error/
│   └── user/
│
├── entity/
│   ├── enums/
│   ├── AuditLog.java
│   ├── BaseEntity.java
│   ├── RefreshToken.java
│   ├── Role.java
│   └── User.java
│
├── exception/
│   ├── GlobalExceptionHandler.java
│   ├── UserAlreadyExistsException.java
│   └── UserNotFoundException.java
│
├── mapper/
│
├── repository/
│   ├── RefreshTokenRepository.java
│   ├── RoleRepository.java
│   └── UserRepository.java
│
├── security/
│   ├── config/
│   ├── jwt/
│   ├── service/
│   └── user/
│
├── service/
│   ├── AuthService.java
│   ├── RefreshTokenService.java
│   └── UserService.java
│
├── util/
├── validation/
│
└── SpringUserManagementApiApplication.java

---

🚀 Getting Started

Requirements

Before running the project, make sure you have:

• ☕ Java 21
• 🐳 Docker & Docker Compose
• 📦 Maven Wrapper

The repository already includes the Maven Wrapper.

---

⚡ Quick Start with Docker

Clone the repository:

git clone https://github.com/ooam-iroo/Spring-User-Management-API.git

Enter the project:

cd Spring-User-Management-API

Start the application:

docker compose up -d

The API will be available at:

http://localhost:8080

---

💻 Local Development

1. Start PostgreSQL

Start PostgreSQL locally or use the PostgreSQL service provided by Docker.

2. Build the project

./mvnw clean package

3. Run the application

./mvnw spring-boot:run

4. Open Swagger

http://localhost:8080/swagger-ui/index.html

---

⚙️ Configuration

Important settings from application.yml:

Property	Default	Description
spring.datasource.url	jdbc:postgresql://localhost:5432/user_management	Database connection
spring.jpa.hibernate.ddl-auto	validate	Schema validation
spring.flyway.enabled	true	Flyway migrations
app.jwt.secret	Change in production	JWT signing key
app.jwt.access-token-expiration	900000	Access token lifetime
app.jwt.refresh-token-expiration	604800000	Refresh token lifetime
server.port	8080	Application port

⚠️ Never use a default or exposed JWT secret in a production environment.

When running with Docker Compose, the database connection is configured to use the PostgreSQL service name:

postgres

---

🗺️ Future Improvements

The following features are planned but are not implemented yet:

• Redis for token blacklisting / caching
• Rate limiting
• Email verification
• Password reset flow
• Full audit logging
• Testcontainers for integration tests
• Kubernetes deployment manifests

---

📜 License

License is not yet defined for this project.

---

🔐 Secure APIs. Clean Architecture. Reliable Backend.

Built with Java & Spring Boot.

⭐ If you find this project useful, consider giving it a star.