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 |