Using and testing Keycloak Rest Api

In this tutorial we want to setup and test the keycloak Rest API with curl. The agent role granted to a user should provide the neccassary roles to allow the Rest API access.

We should already have following setup:

• A new Realm named RBAC
• A realm client named app-client
• A realm user named testadmin with assigned role named agent
• A keycloak server running http://localhost:8280

About Realm Management

Each realm has a built-in client called realm-management. You can view this client by going to the Clients left menu item of your realm. This client defines client-level roles that specify permissions that can be granted to manage the realm.

• view-realm
• view-users
• view-clients
• ..

To allow a user or role to access the Keycloak APi we need to grant this permission either

• directly to specific user or
• use a composite role holding with this permssion

In this tutorial we use the latter one.

Initial Test

• Accessing Keycloak URL /auth/admin/realms/RBAC/users fails with HTTP 403 error

$ ./get-users-via-RBAC-app-client.sh testadmin

 *** Run curl test for user testadmin with 
   secret: 0a32b2ad-7b58-4c5b-bffe-7d3673fe70a3 a
   Keylcloak URL: http://localhost:8280 
   CLIENT_ID: app-client 
   REALM: RBAC
..
* Connected to localhost (127.0.0.1) port 8280 (#0)
> GET /auth/admin/realms/RBAC/users HTTP/1.1
> Host: localhost:8280
> User-Agent: curl/7.79.1
> Accept: */*
> Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiS.. 
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 403 Forbidden

Fix: Add view-users role from realm-management client role via Composite Role feature

• Note; You need to enable Composite Roles checkbox

Rerun Test

$ ./get-users-via-RBAC-app-client.sh
 Connected to localhost (127.0.0.1) port 8280 (#0)
> GET /auth/admin/realms/RBAC/users HTTP/1.1
> Host: localhost:8280
> User-Agent: curl/7.79.1
> Accept: */*
> Authorization: Bearer eyJhbGciOiJSUzI1NiI
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Referrer-Policy: no-referrer
< X-Frame-Options: SAMEORIGIN
< Strict-Transport-Security: max-age=31536000; includeSubDomains
< Cache-Control: no-cache
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< Content-Type: application/json
< content-length: 1104
<
[{"id":"7b7b84e7-00c5-4921-a4ed-7ad0fe78ba99",... 

Curl testscript get-users-via-RBAC-app-client.sh

$ more  get-users-via-RBAC-app-client.sh
#!/bin/bash
#
#  Note: To avoid HTTP 500 with PERMISSION_TOKEN_ERROR on your keycloak server KEYCLOAK_URL must match your
#        auth-server-url in your application.properties file:
#        quarkus.oidc.auth-server-url=http://localhost:8280
#
SECRET=0a32b2ad-7b58-4c5b-bffe-7d3673fe70a3
KEYCLOAK_URL="http://localhost:8280"
REALM="RBAC"
#REALM="master"
#PASSWORD="admin"
PASSWORD="xxx"
CLIENTID="app-client"
#
# For https:
# KEYCLOAK_URL="https://localhost:8543
#
if [ -z "$1" ]; then
    echo -e "\nPlease call '$0 <username> to run this script!\n"
    exit 1
fi
USERNAME=$1
echo -e "\n *** Run curl test for user $USERNAME with secret: $SECRET and Keylcloak URL: $KEYCLOAK_URL -  CLIENT_ID: $CLIENTID - REALM: $REALM \n\n"


echo -e "\n*** Testing  getting the token - If this fails validate your client secret"
curl -X POST \
   ${KEYCLOAK_URL}/auth/realms/${REALM}/protocol/openid-connect/token \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d "grant_type=password&username=${USERNAME}&password=${PASSWORD}&client_id=${CLIENTID}&client_secret=${SECRET}"
echo -e "\n\n"

echo -e "\n*** Saving token access_token variable"
#
export access_token=$(\
  curl -X POST \
   ${KEYCLOAK_URL}/auth/realms/${REALM}/protocol/openid-connect/token \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d "grant_type=password&username=${USERNAME}&password=${PASSWORD}&client_id=${CLIENTID}&client_secret=${SECRET}" | jq --raw-output '.access_token' \
   )

echo -e "\n*** Testing HTTP GET Request"
curl -v -X GET   ${KEYCLOAK_URL}/auth/admin/realms/RBAC/users -H "Authorization: Bearer "$access_token
echo -e "\n********************************************************\n\n"