springboot-ldap-testcontainers

The goal of this project is to create a simple Spring Boot REST API, named simple-service, and secure it using the Spring Security LDAP module. Additionally, Testcontainers will be utilized for integration testing.

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] Implementing and Securing a Simple Spring Boot REST API with LDAP
• [Medium] Implementing and Securing a Spring Boot GraphQL API with LDAP

Project Diagram

Application

• simple-service

  Spring Boot Java Web application that exposes two endpoints:

  • GET /api/public: can be accessed by anyone, it is not secured;
  • GET /api/private: can only be accessed by users authenticated with valid LDAP credentials.

Prerequisites

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

Start Environment

Open a terminal and inside the springboot-ldap-testcontainers root folder run:

docker compose up -d

Import OpenLDAP Users

The LDIF file we will use, simple-service/src/main/resources/ldap-mycompany-com.ldif, contains a pre-defined structure for mycompany.com. Basically, it has 2 groups (employees and clients) and 3 users (Bill Gates, Steve Jobs, and Mark Cuban). Besides, it's defined that Bill Gates and Mark Cuban belong to the employees group, and Steve Jobs belongs to the clients group.

Bill Gates > username: bgates, password: 123
Steve Jobs > username: sjobs, password: 123
Mark Cuban > username: mcuban, password: 123

There are two ways to import those users: by running a script or by using phpLDAPadmin.

Import users running a script

• In a terminal, make sure you are in the springboot-ldap-testcontainers root folder

• Run the following script

  ./import-openldap-users.sh
  

• Check users imported using ldapsearch

  ldapsearch -x -D "cn=admin,dc=mycompany,dc=com" \
    -w admin -H ldap://localhost:389 \
    -b "ou=users,dc=mycompany,dc=com" \
    -s sub "(uid=*)"
  

Import users using phpLDAPadmin

• Access https://localhost:6443

• Login with the following credentials

  Login DN: cn=admin,dc=mycompany,dc=com
  Password: admin
  

• Import the file simple-service/src/main/resources/ldap-mycompany-com.ldif

• You should see something like

Run application with Maven

• In a terminal, make sure you are in the springboot-ldap-testcontainers root folder

• Run the following command to start simple-service

  ./mvnw clean spring-boot:run --projects simple-service
  

Run application as Docker container

• In a terminal, make sure you are in the springboot-ldap-testcontainers root folder

• Build Docker Image

  • JVM

    ./build-docker-images.sh
    

  • Native

    ./build-docker-images.sh native
    

• Environment Variables

  Environment Variable	Description
  LDAP_HOST	Specify host of the LDAP to use (default localhost)
  LDAP_PORT	Specify port of the LDAP to use (default 389)

• Run Docker Container

  docker run --rm --name simple-service -p 8080:8080 \
    -e LDAP_HOST=openldap \
    --network springboot-ldap-testcontainers_default \
    ivanfranchin/simple-service:1.0.0
  

Testing using curl

1. Open a terminal

2. Call the endpoint /api/public

   curl -i localhost:8080/api/public
   

   It should return

   HTTP/1.1 200
   It is public.
   

3. Try to call the endpoint /api/private without credentials

   curl -i localhost:8080/api/private
   

   It should return

   HTTP/1.1 401
   

4. Call the endpoint /api/private again. This time providing username and password

   curl -i -u bgates:123 localhost:8080/api/private
   

   It should return

   HTTP/1.1 200
   bgates, it is private.
   

5. Call the endpoint /api/private providing an invalid password

   curl -i -u bgates:124 localhost:8080/api/private
   

   It should return

   HTTP/1.1 401 
   

6. Call the endpoint /api/private providing a non-existing user

   curl -i -u cslim:123 localhost:8080/api/private
   

   It should return

   HTTP/1.1 401
   

Testing using Swagger

1. Access http://localhost:8080/swagger-ui.html

2. Click GET /api/public to open it; then, click Try it out button and, finally, Execute button.

   It should return

   Code: 200
   Response Body: It is public.
   

3. Click Authorize button (green-white one, located at the top-right of the page)

4. In the form that opens, provide the Bill Gates credentials, i.e., username bgates and password 123. Then, click Authorize button, and to finalize, click Close button

5. Click GET /api/private to open it; then click Try it out button and, finally, Execute button.

   It should return

   Code: 200
   Response Body: bgates, it is private.
   

Shutdown

• To stop the simple-service application, go to the terminal where it is running and press Ctrl+C
• To stop and remove docker compose containers, network, and volumes, in a terminal and inside the springboot-ldap-testcontainers root folder, run the following command

  docker compose down -v
  

Running Test Cases

• In a terminal, make sure you are inside the springboot-ldap-testcontainers root folder

• Run the command below to start the Unit Tests

  ./mvnw clean test --projects simple-service
  

• Run the command below to start the Unit and Integration Tests

  Note: Testcontainers will start the OpenLDAP Docker container automatically before some tests begin and will shut it down when the tests finish.

  ./mvnw clean verify --projects simple-service
  

Cleanup

To remove the Docker image created by this project, go to a terminal and, inside the springboot-ldap-testcontainers root folder, run the following script

./remove-docker-images.sh