This git mono repository is an example Java REST API application that was configured to use Keycloak as access management.
It was bootstrapped using Spring Initializer with the following dependencies:
- RESTful classic (spring-boot-starter-web).
- JUnit Jupiter, Hamcrest and Mockito (spring-boot-starter-test).
- OIDC to enable the integration with Keycloak (spring-boot-starter-oauth2-resource-server).
- Jacoco to generate the coverage test report.
- Spring Data and Hibernate Validator.
- Liquibase (With PostgreSQL as the database).
- TestContainers to run tests in an isolated PostgresSQL database.
- Java Faker to generate test data.
- Lombok to be less verbose in this example.
- Deploy with Jenkins to a self-hosted server with Kubernetes (EC2 or other).
Right after clone the repository, just run the install command inside the root directory:
./mvnw install
Maven will download all the dependencies and run the tests with success.
The Customer Service app is the main Spring Application of this example, it depends on Keycloak and the PostgreSQL.
To start these dependencies run the following command:
cd keycloak && ./keycloak.sh up -d && cd ..
After that:
- Keycloak will be available at
http://localhost:8080/admin/master/console/#/
. For test purpose the username and password is admin/admin. - PostgreSQL will be available at
localhost:5432
. For test purpose the username and password will be postgres/postgres.
Run the Customer Service App.
cd customer-service && ./mvnw spring-boot:run
You should be seen the Spring boot start without ANY error.
The default port is 8081
. If you try the url http://localhost:8081/api/app/build
in the browser you should get a HTTP ERROR 401 (Unauthorized error).
To access this endpoint, you must be authenticated, see the next step to configure the Keycloak and create valid credentials to hit this endpoint.
- Navigate to the url
http://localhost:8080/admin/master/console/#/
and login using the admin/admin credential. - Follow these instructions to create a new realm inside Keycloak. Each realm has its own set of users, roles, and permissions, and a user in one realm is not automatically granted access to resources in another realm.
Let's use Postman to make request to the Customer Service API.
- Create a new Workspace with a meaningful like Spring Boot Application.
- Inside
Collections
, import this Postman collection. - Inside
Environments
, import this Postman environment. Variables of the Postman environment that you must change or double check:- client_secret: You must change the value of this variable with the value that Keycloak generated when you created the Client inside the Realm. Copy it from this place: App (Realm) -> Clients (secure-api) -> Credentials (Tab of the secure-api client) -> Client Secret (click the icon to see the value).
- keycloakClientID, realmUsername and realmPassword: If you followed the values suggested on the PDF of the 4th step, you won't need to change, otherwise, please set them with the values you have used.
- Go to
Collections->Keycloak->Generate Access Token
POST request and click Send button. You should be able to make this request with success.- The
Generate Access Token
request will automatically set the environment variable calledauthToken
that will be required for the next requests.
- The
- Go to
Collections->Customer Service->App Build Version
GET request and click Send button. Now you should be able to make this request with success.
In the same way as App Build version should have worked, the following requests should also work if called in the same order:
Customer Service->Create customer
.Customer Service->Get customer
.Customer Service->List all customers
.Customer Service->Update customer
.Customer Service->Delete customer
.
When opening this repository with IntelliJ, open the root directory secure-api-spring
directly, it will automatically import the common-library
and customer-service
as modules.
When the IDE show the popup Lombok requires enable annotation processing
, click in the button Enable annotation processing
.
You should be able to run tests and debug directly from the IDE normally.
The directories are structured like a Multi Module Project for Spring Boot:
- The common-library directory is a library module, it was created with the purpose to share code between different services.
- The customer-service directory is the main application module of this repository, and it was bootstrapped with the dependencies mentioned above.
- The keycloak directory is not a maven module, however it was created to keep docker images that are used to run Keycloak and PostgreSQL.
PS: For more information about deploy using Jenkins, see the README file of customer-service
above.