A Spring Boot REST API demonstrating secure API development using Spring Security, authentication, authorization, JWT-based security, and layered application architecture.
The project provides a practical reference for building a backend service where APIs are protected using authentication and role-based authorization.
Modern backend services cannot expose business APIs without considering authentication and authorization.
For example, a Book Management API may expose operations such as:
- View books
- Create books
- Update books
- Delete books
However, not every operation should be available to every user.
A typical requirement could be:
Book Service
┌─────────────┐
│ Client │
└──────┬──────┘
│
▼
┌─────────────────┐
│ Authentication │
│ & Authorization │
└────────┬────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
Read Operations Write Operations
USER / ADMIN ADMIN
│ │
└───────────┬───────────┘
▼
Book Service
The problem this project addresses is:
How do we build a Spring Boot REST service where authentication and authorization are enforced consistently before requests reach the business layer?
The project demonstrates how Spring Security can be integrated into a REST API to establish a security boundary between external clients and application functionality.
The application follows a layered architecture with Spring Security acting as the security boundary.
flowchart TB
Client["REST Client<br/>Postman / Browser / Application"]
Security["Spring Security Filter Chain<br/>Authentication + Authorization"]
Controller["REST Controller"]
Service["Service Layer<br/>Business Logic"]
Repository["Repository Layer<br/>Data Access"]
DB[("Database")]
Client -->|HTTP Request + Credentials / JWT| Security
Security -->|Authorized Request| Controller
Controller --> Service
Service --> Repository
Repository --> DB
Security -.->|401 Unauthorized| Client
Security -.->|403 Forbidden| Client
Client
│
│ HTTP Request
│
▼
Spring Security Filter Chain
│
├── Authentication
│
├── Token Validation
│
├── Authorization
│
▼
Controller
│
▼
Service
│
▼
Repository
│
▼
Database
The important architectural principle is:
Security is enforced before the request reaches the application business logic.
Spring Security provides the security boundary around the REST APIs.
HTTP Request
│
▼
┌────────────────────────┐
│ Spring Security Filter │
│ Chain │
└────────────┬───────────┘
│
┌────────┴────────┐
│ │
▼ ▼
Authenticated? Token Valid?
│ │
└────────┬────────┘
▼
Authorization
│
┌─────────┴─────────┐
│ │
▼ ▼
Allowed Denied
│ │
▼ ├──► 401
Controller │
└──► 403
Authentication answers:
Who is the caller?
Authorization answers:
What is the caller allowed to do?
Keeping these concepts separate is fundamental to designing secure APIs.
When JWT authentication is enabled, the client sends a token with the request:
Authorization: Bearer <JWT>The request flow becomes:
Client
│
│ Authorization: Bearer JWT
▼
Spring Security
│
├── Extract JWT
├── Validate token
├── Validate signature
├── Extract user/roles
└── Build SecurityContext
│
▼
Controller
The application can then use the authenticated identity and authorities when evaluating access to protected endpoints.
A secure API typically needs both.
Who are you?
│
▼
JWT / Credentials
│
▼
Authenticated User
What can you do?
│
▼
Roles / Authorities
│
▼
Endpoint Access
Example:
USER
├── GET /books
└── GET /books/{id}
ADMIN
├── GET /books
├── POST /books
├── PUT /books/{id}
└── DELETE /books/{id}
Adjust the exact endpoint/role mapping above to match the current security configuration in the project.
The project follows a conventional Spring Boot layered architecture:
Controller
│
▼
Service
│
▼
Repository
│
▼
Database
Responsible for:
- HTTP endpoints
- Request mapping
- Request/response handling
- Validation boundaries
Responsible for:
- Business logic
- Transaction boundaries
- Domain operations
Responsible for:
- Database access
- Persistence operations
- Query execution
Cross-cuts the request path before the controller:
Security
│
▼
Controller
│
▼
Service
│
▼
Repository
| Technology | Purpose |
|---|---|
| Java | Application development |
| Spring Boot | Backend framework |
| Spring Web | REST APIs |
| Spring Security | Authentication & authorization |
| JWT | Stateless authentication |
| Spring Data | Persistence |
| Gradle / Maven | Build automation |
| JUnit | Testing |
The repository is a Java-based Spring Boot project and is described on your GitHub profile as a book service with Spring Security enabled.
Install:
- JDK 25
- Git
- Gradle or Maven, depending on the project build configuration
- An IDE such as IntelliJ IDEA or VS Code
- Postman or another REST client
Verify Java:
java -versiongit clone https://github.com/ashutoshsahoo/book-service.git
cd book-servicemvn clean packagemvn spring-boot:runThe application will start using the configured Spring Boot server port.
Use Postman, curl, or another REST client to interact with the API.
A typical API workflow is:
1. Authenticate
│
▼
2. Obtain JWT
│
▼
3. Send JWT in Authorization header
│
▼
4. Access protected Book APIs
Example:
Authorization: Bearer <JWT>The service provides APIs for managing books.
Typical REST operations include:
| Operation | HTTP Method | Purpose |
|---|---|---|
| Create | POST |
Create a book |
| Read | GET |
Retrieve books |
| Update | PUT |
Update a book |
| Delete | DELETE |
Delete a book |
Example REST model:
{
"title": "Designing Data-Intensive Applications",
"author": "Martin Kleppmann"
}The exact endpoint paths and request/response models should be kept synchronized with the controller implementation.
A secure API should clearly distinguish authentication and authorization failures.
The client has not successfully authenticated.
Examples:
Missing token
Invalid token
Expired token
Invalid credentials
The client is authenticated but does not have sufficient permissions.
Example:
Authenticated USER
│
▼
DELETE /books/10
│
▼
403 Forbidden
This distinction is important when designing and troubleshooting secured REST APIs.
This project demonstrates:
- Authentication
- Authorization
- JWT-based security
- Stateless API security
- Spring Security filter chain
- Security context
- Role/authority-based access control
- Protected REST endpoints
- HTTP
401vs403handling
Security-focused testing should cover both successful and unsuccessful scenarios.
✓ Valid credentials
✓ Invalid credentials
✓ Missing credentials
✓ Invalid JWT
✓ Expired JWT
✓ Authorized USER access
✓ Authorized ADMIN access
✓ USER attempting ADMIN operation
✓ Unauthenticated access
✓ Create book
✓ Retrieve book
✓ Update book
✓ Delete book
✓ Invalid book request
✓ Non-existent book
Check:
Authorization: Bearer <JWT>
Also verify:
- JWT is valid
- JWT has not expired
- Authorization header is present
- Security configuration permits the endpoint
The request is authenticated, but the authenticated principal does not have the required authority/role.
Check the role/authority contained in the authenticated security context.
For REST APIs, unexpected redirects to /error can often indicate an exception occurring during request processing or
security handling.
Check the application logs for the original exception before troubleshooting the /error endpoint itself.
A typical structure for the service is:
book-service/
│
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── ...
│ │ │
│ │ └── resources/
│ │ ├── application.yml
│ │ └── ...
│ │
│ └── test/
│ └── ...
│
├── Dockerfile
├── pom.xml
└── README.md
The application can be containerized using Docker.
Example:
docker build -t book-service:latest .Run:
docker run \
-p 8080:8080 \
book-service:latestFor production deployments, consider:
- Non-root containers
- Multi-stage Docker builds
- Minimal JRE images
- Container vulnerability scanning
- Resource limits
- Health probes
- Externalized configuration
- Secret management
The service can be extended into a Kubernetes workload:
Kubernetes Cluster
│
┌──────▼──────┐
│ Service │
└──────┬──────┘
│
┌──────────┴──────────┐
▼ ▼
Spring Boot Pod Spring Boot Pod
│ │
└──────────┬──────────┘
▼
Database
Potential Kubernetes capabilities include:
- Deployment
- Service
- ConfigMap
- Secret
- Readiness probe
- Liveness probe
- Horizontal Pod Autoscaler
- Resource requests and limits
- Ingress / Gateway API
For a production-grade Spring Security service, consider adding:
- OAuth 2.0 / OpenID Connect
- External Identity Provider
- Key rotation
- Refresh-token strategy
- Fine-grained authorities
- Method-level security
- CORS policy
- CSRF strategy appropriate for the API
- Rate limiting
- Audit logging
Do not store:
JWT secret
Database password
API keys
Private keys
directly in source control.
Use:
- Kubernetes Secrets
- HashiCorp Vault
- Cloud secret managers
- External Secrets Operator
Add:
- Spring Boot Actuator
- Micrometer
- Prometheus
- Grafana
- OpenTelemetry
- Distributed tracing
- Structured logging
After working through this project, you should understand:
- How a Spring Boot REST API is structured.
- How Spring Security intercepts HTTP requests.
- How authentication differs from authorization.
- How JWT enables stateless authentication.
- How roles/authorities control API access.
- How
401and403differ. - How security concerns can be separated from business logic.
- How a secured Spring Boot service can be containerized and deployed.
The service can be evolved toward a production-grade backend by adding:
API Gateway
│
▼
┌─────────────┐
│ Book Service│
└──────┬──────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Database Redis Cache Kafka
│
▼
Event Consumers
Potential extensions:
- OAuth2 Resource Server
- Keycloak / external Identity Provider
- Redis caching
- Kafka domain events
- Outbox pattern
- PostgreSQL
- OpenTelemetry
- Prometheus + Grafana
- Docker
- Kubernetes
- CI/CD
- Contract testing
- Testcontainers
This project demonstrates a fundamental backend engineering principle:
Security should be treated as an architectural boundary, not as logic implemented independently inside every business operation.
Spring Security provides that boundary, while the application layers remain focused on their respective responsibilities:
Security Boundary
│
▼
┌─────────────────┐
│ Controller │
└────────┬────────┘
▼
┌─────────────────┐
│ Service │
└────────┬────────┘
▼
┌─────────────────┐
│ Repository │
└────────┬────────┘
▼
Database
This repository serves as a practical reference for building secure Spring Boot REST APIs with authentication, authorization and JWT-based security.