This project shows a simple REST API to manage customer data. It is built using Spring Boot and Keycloak.
-
Download the Keycloak Docker image by running
docker pull quay.io/keycloak/keycloak
-
Run the Authorization Server (AS) with:
docker run --name AS -e KEYCLOAK_USER=master -e KEYCLOAK_PASSWORD=master -e KEYCLOAK_IMPORT=/tmp/realm-config.json -v <path>/realm-config.json:/tmp/realm-config.json -p 8080:8080 -it quay.io/keycloak/keycloak
Note that the above command:
- Creates a
master
user that has full control of the AS. - Set a volume mapping in order to pass as argument the realm configuration file realm-config.json, being
<path>
the address of that file in your local machine. - Imports the realm configuration file realm-config.json. This file defines a realm (named first-realm) with a single client (named first-client) and two realm-roles (USER and ADMIN).
- Enable the AS at port 8080.
- Creates a
-
Head over
http://localhost:8080/auth/
, click onAdministration Console
and fill in the form with master as username and password. -
Create a new user with ADMIN role. To do so:
- Click on
Users
, and thenAdd user
. - Fill in the form (only
Username
is required) and save. - Go to
Role Mappings
and add the ADMIN role to assigned roles. - If desired, go to
Credentials
and set a password for this newly created ADMIN user.
- Click on
-
After the AS initial configuration, you can start the Resource Server (RS) in a separate terminal via
mvn package spring-boot:run
, from the project directory. This will make available at port 8081 the RS.
The developed API is secured via OAuth 2.0 protocol, so that every request must hold a valid Access Token. In order to do that, the OAuth 2.0 Authorization Code flow has to be followed:
-
Place a GET request with the browser at:
http://localhost:8080/auth/realms/first-realm/protocol/openid-connect/auth?client_id=first-client&response_type=code&scope=openid profile&redirect_uri=http://localhost:8082/callback&state=wtfmnnn
The above is the request from the client for a code. The AS will then response, if everything is ok, at
redirect_uri=http://localhost:8082/callback
with the code as a url query parameter. -
With that code, POST a request at
http://localhost:8080/auth/realms/first-realm/protocol/openid-connect/token
. The code, and another OAuth required info, has to be in form parameters. For simplicity, use the OAUTH.postman_collection.json provided with the project. Note that theclient_secret
parameter can be found by themaster
user underClients >> first-client >> Credentials >> Regenerate Secret
-
Keycloak will response with the Access Token, so that now you can insert it on every request. The insertion has to be made in the Authorization header, as Bearer.
-
The Resource Server exposed endpoints are (the ones under
/admin
require the user to have ADMIN role):- GET ~/user/customers
- GET ~/user/customers/{id}
- POST ~/user/customers
- PUT ~/user/customers
- DELETE ~/user/customers/{id}
- GET ~/user/customers/{id}/image
- POST ~/user/customers/{id}/image
- GET ~/admin/users
- GET ~/admin/users/{id}
- POST ~/admin/users
- PUT ~/admin/users
- DELETE ~/admin/users/{id}
-
Examples of all these HTTP requests, both to the Resource Server and the Authorization Server, can be found in the Postman collections provided with the project: