spring-boot-nginx-keycloak-cluster

The goal of this project is to use Nginx as a reverse proxy and load balancer for a Keycloak cluster with two instances and a Spring Boot application, called simple-service, also with two instances. The simple-service app will use Keycloak for IAM.

Proof-of-Concepts & Articles

On ivangfr.github.io, I have compiled my Proof-of-Concepts (PoCs) and articles. You can easily search for the technology you are interested in by using the filter. Who knows, perhaps I have already implemented a PoC or written an article about what you are looking for.

Additional Readings

• [Medium] Using Nginx to Load Balance Requests to a Spring Boot Web application
• [Medium] Using Nginx to Load Balance Requests to a Keycloak Cluster
• [Medium] Nginx Load Balancing Requests to a Keycloak Cluster and a Spring Boot app that uses Keycloak as IAM

Project Diagram

Application

• simple-service

  Spring Boot Web Java application that exposes the following endpoints:

  • GET /api/public: This endpoint is not secured; everyone can access it;
  • GET /api/secured: This endpoint is secured and can only be accessed by users who provide a JWT access token issued by Keycloak. The token must include the role APP_USER.

Prerequisites

• Java 21 or higher;
• A containerization tool (e.g., Docker, Podman, etc.)
• jq

Building simple-service Docker Image

• In a terminal, navigate to the spring-boot-nginx-keycloak-cluster root folder.

• Run the following script:

  ./build-docker-images.sh

Configure /etc/hosts

Add the following line to /etc/hosts

127.0.0.1 keycloak-cluster.lb simple-service.lb

Starting Environment

Open a terminal and inside the spring-boot-nginx-keycloak-cluster root folder run:

./init-environment.sh

This script will start:

• one PostgreSQL Docker container;
• two Keycloak Docker containers;
• two simple-service Docker containers;
• one Nginx Docker container;

Configuring Keycloak

We can configure a client for simple-service in Keycloak using the Keycloak website at http://keycloak-cluster.lb. However, to keep things simple and fast, we have created a script for it.

So, in a terminal, make sure you are inside the spring-boot-nginx-keycloak-cluster root folder, run the script below:

./init-keycloak.sh

The script will:

• create company-services realm;
• disable the required action Verify Profile;
• create simple-service client;
• create the client role APP_USER for the simple-service client;
• create USERS group;
• assign APP_USER client role to USERS group;
• create user-test user;
• assign USERS group to user-test;

To complete, copy the SIMPLE_SERVICE_CLIENT_SECRET value shown at the end of the script. It will be needed whenever we call Keycloak to get a JWT access token to access simple-service.

Testing the simple-service endpoints

1. Open a new terminal;

2. Call the endpoint GET /public:

   curl -i http://simple-service.lb/public

   It should return:

   HTTP/1.1 200
   ...
   Hi World, I am a public endpoint
   

3. Try to call the endpoint GET /secured without authentication:

   curl -i http://simple-service.lb/secured

   It should return:

   HTTP/1.1 401
   ...
   

4. Create an environment variable that contains the Client Secret generated by Keycloak to simple-service at Configure Keycloak step:

   SIMPLE_SERVICE_CLIENT_SECRET=...

5. Run the command below to get an access token for user-test user:

   USER_TEST_ACCESS_TOKEN="$(curl -s -X POST \
     "http://keycloak-cluster.lb/realms/company-services/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=user-test" \
     -d "password=123" \
     -d "grant_type=password" \
     -d "client_secret=$SIMPLE_SERVICE_CLIENT_SECRET" \
     -d "client_id=simple-service" | jq -r .access_token)"
   echo $USER_TEST_ACCESS_TOKEN

6. Call the endpoint GET /secured:

   curl -i http://simple-service.lb/secured -H "Authorization: Bearer $USER_TEST_ACCESS_TOKEN"

   It should return:

   HTTP/1.1 200
   ...
   Hi user-test, I am a secured endpoint
   

7. The default expiration period for the access token is 5 minutes. So, wait for this time and then, using the same access token, try to call the secured endpoint.

   It should return:

   HTTP/1.1 401
   ...
   WWW-Authenticate: Bearer error="invalid_token", error_description="An error occurred while attempting to decode the Jwt: Jwt expired at ...", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"
   ...
   

8. Checking Keycloak and simple-service Docker container logs

   We can verify that Nginx is appropriately load balancing the requests when an access token request to Keycloak is made. To view the Keycloak Docker container logs, execute the following commands in different terminals:

   docker logs -f keycloak1
   docker logs -f keycloak2

   We can also verify that Nginx is appropriately load balancing requests to the simple-service endpoints. To view the simple-service Docker container logs, execute the following commands in different terminals:

   docker logs -f simple-service1
   docker logs -f simple-service2

Useful Links & Commands

• Keycloak

  The Keycloak website can be accessed at http://keycloak-cluster.lb

• Nginx

  If you wish to modify the Nginx configuration file without restarting its Docker container, follow these steps:

  • Apply the changes in the nginx/nginx.conf file;
  • Execute the following command to access the nginx Docker container:

    docker exec -it nginx bash

  • In the nginx Docker container terminal, run:

    nginx -s reload

  • To exit, just run the command exit.

Shutdown

To stop and remove Docker containers, network, and volumes, open a terminal, navigate to the spring-boot-nginx-keycloak-cluster root folder, and run the following script:

./shutdown-environment.sh

Cleanup

To remove the simple-service Docker image created, open a terminal, navigate to the spring-boot-nginx-keycloak-cluster root folder, and run the following script:

./remove-docker-images.sh