Skip to content
Hands-on IT IT Drills

Appendix A: Cheat Sheet

Everything important from Days 0–15 on a few pages. The number in parentheses is the day on which you practiced it. When in doubt, www.keycloak.org/docs, www.keycloak.org/server/all-config and kcadm.sh --help are authoritative.

Start of the Day and Training Ground

source ~/kc-lab/setup/env.sh        # LAB, VM_IP, KC_URL, NOTES_URL, REALM (0)
kclogin                             # log kcadm in as kcadmin (2)
TOKEN=$(token)                      # access token for anna (3)
TOKEN=$(token ben lab-user-pw-456)  # for another user (3)
jwt "$TOKEN" | jq .                 # make the payload readable (3)
api() { docker run --rm --network lab curlimages/curl:8.17.0 -s "$@"; }   # (4)
Address Purpose Day
$KC_URL (8080, from Day 12 on https on 443) Keycloak 1, 12
127.0.0.1:9000 /health/ready, /health/live, /metrics 1, 12
$NOTES_URL (4180) notes behind oauth2-proxy 4
ldap:389, 127.0.0.1:389 OpenLDAP dc=notes,dc=lab 6
dc1.ad.notes.lab:636 Samba AD via LDAPS 9
localhost:8081 trial instance for upgrades 12

OIDC Endpoints

Under $KC_URL/realms/<realm>/protocol/openid-connect/…:

Endpoint Purpose Day
../.well-known/openid-configuration discovery: all addresses 3
auth login in the browser (authorization code, PKCE) 3, 4
token fetch token, refresh (refresh_token) 3
userinfo claims for the access token 3
token/introspect check token, only for clients in aud 3, 5
certs JWKS, public keys 3
logout end session, with id_token_hint 4
Grant For Day
authorization_code + PKCE browser applications 3, 4
client_credentials services, automation 3, 13
password lab and tests only 3
refresh_token refresh token 3, 12

kcadm.sh

kcadm get users -r lab -q username=anna -q exact=true    # exact search (2)
kcadm create users -r lab -s username=x -s enabled=true  # create (2)
kcadm set-password -r lab --username x --new-password …  # password (2, 10)
kcadm add-roles -r lab --uusername x --rolename notes-lesen        # realm role (2)
kcadm add-roles -r lab --uusername service-account-automation \
  --cclientid realm-management --rolename manage-users             # admin right (13)
kcadm update clients/$ID -r lab -s 'redirectUris=["…"]'            # change (4)
kcadm get … | sed … | kcadm update … -f -                          # rewrite (12)
kcadm create clear-user-cache -r lab                               # clear cache (8)
kcadm create "realms/lab/partial-export?exportClients=true" -o     # configuration (12)
kcadm create partialImport -r lab -f -                             # restore (15)

Pitfalls: -q username= searches substrings (2); --fields doesn’t show some fields – better use jq (5, 11); files for -f must go into the container (5), -f - reads from stdin (12); after recreating the containers, kclogin again (12).

Realm Building Blocks

Building block Rule of thumb Day
Composite role role that contains other roles 2
Group passes roles on to members 2, 8
Client role sits under resource_access, puts the client into aud 5, 15
Client scope bundle of mappers, default or optional 5
Audience mapper writes a client into aud 5
User profile unknown attributes are discarded 5
Required action task at the next login, blocks the password grant 10
Flow chain of executions, change a copy instead of the original 11
Identity provider login via another IdP, copy of the user 11

Directories

Setting Meaning Day
READ_ONLY / WRITABLE Keycloak does (not) write to the directory 7
importEnabled copy of the users in the database 7
triggerFullSync / triggerChangedUsersSync reconciliation, deletes no users 7
group-ldap-mapper groups from groupOfNames/memberOf 8, 9
useTruststoreSpi + conf/truststores LDAPS with your own CA 9
MSAD account controls disabled AD accounts (userAccountControl) 9

Operations

Option Purpose Day
KC_HOSTNAME public address, determines iss 1, 12
KC_PROXY_HEADERS=xforwarded behind a reverse proxy 12
KC_HTTP_ENABLED allow HTTP (TLS at the proxy) 1, 12
KC_HEALTH_ENABLED, KC_METRICS_ENABLED port 9000 1, 12
KC_BOOTSTRAP_ADMIN_* temporary admin at the first start 1
kc.sh export --realm lab --users realm_file realm as JSON 12
kc.sh update-compatibility metadata/check rolling or recreate 12, 14

Operator

kubectl -n keycloak get keycloak kc                       # status (14)
kubectl -n keycloak wait keycloak/kc --for=condition=Ready --timeout=900s
kubectl -n keycloak get secret kc-initial-admin -o jsonpath='{.data.username}'
kubectl -n keycloak patch keycloak kc --type=merge -p '{"spec":{"image":"…"}}'

Install four CRDs, startOptimized: false with the standard image, update.strategy: Auto for checked upgrades (14).

Error Patterns

Message Cause Day
Invalid parameter: redirect_uri address not in redirectUris 15
unauthorized_client wrong client secret 15
Invalid user credentials password, missing OTP or locked account (check the log!) 10, 15
Account is not fully set up pending required action 10
unknown_error error in Keycloak, e.g. LDAP gone – read the log 15
active:false on introspection requesting client not in aud 3, 5
Audience "notes-api" fehlt (notes-api) audience mapper missing 5, 15
email … isn't verified (oauth2-proxy) broker without Trust email 11
Client secret must be re-entered … token URL of an IdP changed 12
'--optimized' flag was used for first … startOptimized: false missing 14
curl: (60) SSL certificate problem certificate or CA doesn’t match 12, 15