Lightweight RESTful API with Spring Boot 3, Keycloak 21, Docker, PostgreSQL, JPA, Lombok, OpenAPI, etc.
- Download Docker Here. Hint: Enable Hyper-V feature on windows and restart;
- Then open powershell and check:
docker info
or check docker version
docker -v
or docker compose version
docker-compose -v
- Clone the repository:
git clone https://github.com/OKaluzny/spring-boot-docker-postgres.git
- Build the maven project:
mvn clean install
- Running the containers:
This command will build the docker containers and start them.
docker-compose up
or
This is a similar command as above, except it will run all the processes in the background.
docker-compose -f docker-compose.yml up
Appendix A.
All commands should be run from project root (where docker-compose.yml locates)
- If you have to want to see running containers. Checklist docker containers
docker container list -a
or
docker-compose ps
Screenshot with runnings containers
Create Initial Admin User
go to http://localhost:8080/auth and fill in the create initial admin form with username as admin
and password as the Pa55w0rd
.
Keycloak — Create Initial Admin
Click Create and proceed to administration console and then login with your created initial admin.
The first screen Keycloak shows after login is the Master realm details.
Keycloak — Master Realm Details
Let’s name our first realm automobile
:
Roles are used to categorize the user. In an application, the permission to access resources is often granted to the role rather than the user. Admin, User, and Manager are all typical roles that may exist in an organization.
To create a role, click the “Roles” menu on the left followed by the “Add Role” button on the page.
Keycloak does not come with any pre-created user, so let’s create our first user, “Oleg” Click on the Users
menu on the left and then click the Add User
button.
Oieg will require a password to login to Keycloak. Create a password credential for user your Oleg. Click on the “Credentials” tab and write both password and password confirmation as the password
. Turn off the Temporary password
switch so we do not need to change the password on the next login. Click “Set Password” to save your password credential.
Finally, you need to assign the created PERSON
role to Oleg. To do this, click on the Role Mappings tab, select the PERSON role, and click on “add selected”.
Clients are entities that will request the authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single-sign-on. These clients just want Keycloak to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
Let’s create a client that we will use to secure our Spring Boot REST service.
Click on the Clients menu on the left and then click on Add Client.
In the form, fill Client Id as app
, select OpenID Connect
for the Client Protocol and click Save.
In the client details form, we need to change the Access Type
to confidential
instead of defaulted public (where client secret is not required). Turn on the “Authorization Enabled”
switch before you save the details.
A client requests a security token by making a Token Exchange request to the token endpoint in Keycloak using the HTTP POST method.
Go to http://localhost:8080/auth/realms/automobile/protocol/openid-connect/token
Postman — Token Exchange Request
It is expected to receive a JSON response with an access token
and refresh token
together with other accompanying details.
The received access token
can be used in every request to a Keycloak secured resource by simply placing it as a bearer token in the Authorization
header:
Postman — Token Exchange Request
or generate new access token
and refresh token
Postman — Token Exchange Request
Go to http://localhost:8088/demo/api/automobiles to test and would specify OAuth 2.0 authorization redirect a username: oleg
and password: admin
- GET request to
/api/automobiles/
returns a list of "automobiles"; - GET request to
/api/automobiles/1
returns the "automobile" with ID 1; - POST request to
/api/automobiles/
with a "automobile" object as JSON creates a new "automobile"; - PUT request to
/api/automobiles/3
with a "automobile" object as JSON updates the "automobile" with ID 3; - DELETE request to
/api/automobiles/4
deletes the "automobile" with ID 4; - DELETE request to
/api/automobiles/
deletes all the "automobiles".
- GET request to
/api/automobiles?color=madeira-violet
returns the "automobile"`s with color madeira-violet; - GET request to
/api/automobiles?name=BMW&color=techno-violet
returns the "automobile"`s with name BMW and color techno-violet; - GET request to
/api/automobiles?colorStartsWith=Ma&page=0&size=2
returns the "automobile"`s with color which starts with "m". Included Pagination and sorting;
or use Swagger API http://localhost:8088/demo/swagger-ui.html
and generation API docks http://localhost:8088/demo/v3/api-docs.yaml
Appendix B.
- Do not forget, if you see db, open the Windows Services Manager on your Windows 10 computer and stop postgres
- Check all the images you have:
docker images
- Stop containers:
docker-compose down
- Remove old stopped containers of docker-compose
docker-compose rm -f