API — Keycloak Operations

The project makes use of Keycloak as an identity and access manager. This means that every endpoint on the API must have a valid authentication token in order to resolve the request successfully. There is one exception, the actuator endpoints.

Preloaded User

Accompanying the back-end project’s infrastructural pieces, is a fully preconfigured Keycloak realm with a preloaded user with the role of SYS_ADMIN.

The details of the user is as follows:

username   =  walthersmulders
password   =  walthersmulders
role       =  SYS_ADMIN

We’ll make use of the details shown above to interact with Keycloak’s API in order to perform various operations related to tokens and authentication.

To obtain a valid access_token value, you will need to perform an API request to the token endpoint that Keycloak provides.

The endpoint in question looks like this when the default configuration is used:

http://localhost:8024/realms/canyonlands/protocol/openid-connect/token

http://localhost:8024
- This is the host and port on which the Keycloak service runs.
/realms/canyonlands/
- This is the realm within Keycloak in question. For this project the realm name is canyonlands.
/protocol/openid-connect/token
- This part indicates that a specific protocol is used, in this case the OpenID Connect protocol, which is an extension of OAuth 2.0

Now that we’ve established the endpoint to be used, let’s take a look at the steps involved:

Perform a Login and get a token:

curl --location 'http://localhost:8024/realms/canyonlands/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=canyonlands' \
--data-urlencode 'username=walthersmulders' \
--data-urlencode 'password=walthersmulders' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_secret=yWbjVxoipwXoqSmruM13IJ2GSvQHrM2K'

This should provide a response like:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi....",
  "expires_in": 18000,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiw....",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "dd1dfd3d-9d8d-45c0-a5ed-7a265e10182d",
  "scope": "profile email"
}

Copy the access_token value for use in subsequent API calls.

This concludes the guide to obtain an access_token with the dedicated Keycloak endpoint. When the front-end application is available, the user will not have to interact with this endpoint via Postman or cURL requests, this will all happen through redirects and front-end logic.

API — Keycloak Operations

Preloaded User

Login and Obtain Access Token