Secure API with Spring Boot 3

This Git monorepository contains a sample Java REST API application configured to use Keycloak for access management.

The project was bootstrapped using Spring Initializer with the following dependencies:

• Spring Boot Web (spring-boot-starter-web) for building RESTful APIs.
• JUnit Jupiter, Hamcrest, and Mockito (spring-boot-starter-test) for unit testing.
• Spring Security OAuth2 Resource Server (spring-boot-starter-oauth2-resource-server) to enable OIDC integration with Keycloak.
• Jacoco for generating test coverage reports.
• Spring Data and Hibernate Validator for data access and validation.
• Redis is used as 2nd level cache (Using Redisson driver).
• Spring Doc Open API for API documentation.
• Liquibase with PostgreSQL as the database for managing database migrations.
• TestContainers to run tests in an isolated PostgreSQL database environment.
• Data Faker for generating test data.
• Lombok to reduce verbosity in the code.
• Jenkins for deploying to a self-hosted Kubernetes server.

Requirements

1. Java JDK version 21 or higher.
2. Docker version 27 or higher.

Initial steps

1st step

This example relies on Keycloak for authentication, PostgreSQL as the database as Redis for cache. To start these dependencies, run the following commands:

./task.sh services:up

2nd step

After cloning the repository, navigate to the root directory of the project and run the following command:

./mvnw clean install

3rd step

To run the customer service, use the following command in another terminal:

./mvnw -pl customer-svc spring-boot:run

Try it out

You can test the API using the Swagger UI at the following URL:

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

1. Click the Authorize button and enter secure-api in the client_id field.
2. Click the Authorize button of the popup, which will redirect you to the Keycloak authentication page.

When the Keycloak service runs for the first time, it imports a realm called App, created exclusively for testing purposes.

This realm contains two users for authentication:

• The user with the administrator role (ROLE_ADMIN) has the username admin and password password.
• The user with the analyst role (ROLE_ANALYST) has the username analyst and password password.

Note: The ROLE_ADMIN user is permitted to modify customers, while the ROLE_ANALYST user can only list them.

Once you have authenticated, you can begin testing the API endpoints using the Try it out button for each endpoint.

If you would like to view the JWT token generated by Keycloak, use the following URL, which redirects the authentication flow to jwt.io:

http://localhost:9080/realms/app/protocol/openid-connect/auth?response_type=token&client_id=secure-api&redirect_uri=https%3A%2F%2Fjwt%2Eio

Keycloak

Since Keycloak 25, the Organization feature is available to support multi-tenancy as can be seen here.

When using the Customer API endpoints, the User and Organization of the Keycloak authenticated token are going to be synced in the Customers database.

The admin console is accessible at http://localhost:9080/admin/master/console/#/. For testing purposes, the super admin user credentials are as follows:

• Username: admin
• Password: admin

PostgreSQL

The is available at localhost:5432. For testing purposes, the superuser credentials are:

• Username: postgresql
• Password: postgresql

Modules

The modules of this repository is based on the structure of a Multi Module Project for Spring Boot:

The auth-lib directory is a library designed to share the code need to handle authenticated resources, like authenticated user and organization for Multi-tenancy.

The customer-svc module is the main app of this repository, bootstrapped with the dependencies mentioned earlier.

Docker

The docker directory is not a Maven module.

• The jenkins directory contains a Dockerfile that is used to build the Docker Agent image, which will be utilized in the Pipeline.
• The postgresql directory contains a Dockerfile to build the image for PostgreSQL used in this example. For development convenience, when the container runs for the first time, it will create two databases by default: one for Keycloak and one for PostgreSQL.
• The keycloak directory contains a Docker Compose template to run Keycloak. For convenience, when it runs for the first time, it will import a development realm and enable the organization feature.

Jenkins

See here for more details on how to build the Docker image using Jenkins, push the built image to the Docker Image Registry, and deploy it to Kubernetes.