Zum Inhalt springen
Trainingslager IT-Trainingslager

Anhang A: Spickzettel

Alles Wichtige aus Tag 0–15 auf wenigen Seiten. Die Zahl in Klammern ist der Tag, an dem du es geübt hast. Im Zweifel gelten www.keycloak.org/docs, www.keycloak.org/server/all-config und kcadm.sh --help.

Tagesstart und Gelände

source ~/kc-lab/setup/env.sh        # LAB, VM_IP, KC_URL, NOTES_URL, REALM (0)
kclogin                             # kcadm als kcadmin anmelden (2)
TOKEN=$(token)                      # Access Token für anna (3)
TOKEN=$(token ben lab-user-pw-456)  # für einen anderen Benutzer (3)
jwt "$TOKEN" | jq .                 # Payload lesbar machen (3)
api() { docker run --rm --network lab curlimages/curl:8.17.0 -s "$@"; }   # (4)
Adresse Zweck Tag
$KC_URL (8080, ab Tag 12 https auf 443) Keycloak 1, 12
127.0.0.1:9000 /health/ready, /health/live, /metrics 1, 12
$NOTES_URL (4180) notes hinter oauth2-proxy 4
ldap:389, 127.0.0.1:389 OpenLDAP dc=notes,dc=lab 6
dc1.ad.notes.lab:636 Samba AD per LDAPS 9
localhost:8081 Probe-Instanz für Upgrades 12

OIDC-Endpunkte

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

Endpunkt Zweck Tag
../.well-known/openid-configuration Discovery: alle Adressen 3
auth Login im Browser (Authorization Code, PKCE) 3, 4
token Token holen, erneuern (refresh_token) 3
userinfo Claims zum Access Token 3
token/introspect Token prüfen, nur für Clients in aud 3, 5
certs JWKS, öffentliche Schlüssel 3
logout Sitzung beenden, mit id_token_hint 4
Grant Wofür Tag
authorization_code + PKCE Browser-Anwendungen 3, 4
client_credentials Dienste, Automatisierung 3, 13
password nur Labor und Tests 3
refresh_token Token erneuern 3, 12

kcadm.sh

kcadm get users -r lab -q username=anna -q exact=true    # exakt suchen (2)
kcadm create users -r lab -s username=x -s enabled=true  # anlegen (2)
kcadm set-password -r lab --username x --new-password …  # Passwort (2, 10)
kcadm add-roles -r lab --uusername x --rolename notes-lesen        # Realm-Rolle (2)
kcadm add-roles -r lab --uusername service-account-automation \
  --cclientid realm-management --rolename manage-users             # Admin-Recht (13)
kcadm update clients/$ID -r lab -s 'redirectUris=["…"]'            # ändern (4)
kcadm get … | sed … | kcadm update … -f -                          # umschreiben (12)
kcadm create clear-user-cache -r lab                               # Cache leeren (8)
kcadm create "realms/lab/partial-export?exportClients=true" -o     # Konfiguration (12)
kcadm create partialImport -r lab -f -                             # zurückspielen (15)

Stolpersteine: -q username= sucht Teilstrings (2); --fields zeigt manche Felder nicht – lieber jq (5, 11); Dateien für -f müssen in den Container (5), -f - liest von stdin (12); nach Neustart der Container wieder kclogin (12).

Realm-Bausteine

Baustein Merksatz Tag
Composite-Rolle Rolle, die andere Rollen enthält 2
Gruppe vererbt Rollen an Mitglieder 2, 8
Client-Rolle steht unter resource_access, setzt den Client in aud 5, 15
Client Scope Bündel aus Mappern, Default oder Optional 5
Audience-Mapper schreibt einen Client in aud 5
User Profile unbekannte Attribute werden verworfen 5
Required Action Aufgabe beim nächsten Login, blockiert Password Grant 10
Flow Kette von Executions, Kopie statt Original ändern 11
Identity Provider Login über anderen IdP, Kopie des Benutzers 11

Verzeichnisse

Einstellung Bedeutung Tag
READ_ONLY / WRITABLE Keycloak schreibt (nicht) ins Verzeichnis 7
importEnabled Kopie der Benutzer in der Datenbank 7
triggerFullSync / triggerChangedUsersSync Abgleich, löscht keine Benutzer 7
group-ldap-mapper Gruppen aus groupOfNames/memberOf 8, 9
useTruststoreSpi + conf/truststores LDAPS mit eigener CA 9
MSAD account controls gesperrte AD-Konten (userAccountControl) 9

Betrieb

Option Zweck Tag
KC_HOSTNAME öffentliche Adresse, bestimmt iss 1, 12
KC_PROXY_HEADERS=xforwarded hinter Reverse Proxy 12
KC_HTTP_ENABLED HTTP erlauben (TLS am Proxy) 1, 12
KC_HEALTH_ENABLED, KC_METRICS_ENABLED Port 9000 1, 12
KC_BOOTSTRAP_ADMIN_* temporärer Admin beim ersten Start 1
kc.sh export --realm lab --users realm_file Realm als JSON 12
kc.sh update-compatibility metadata/check rolling oder recreate 12, 14

Operator

kubectl -n keycloak get keycloak kc                       # Zustand (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":"…"}}'

Vier CRDs installieren, startOptimized: false beim Standard-Image, update.strategy: Auto für geprüfte Upgrades (14).

Fehlerbilder

Meldung Ursache Tag
Invalid parameter: redirect_uri Adresse nicht in redirectUris 15
unauthorized_client falsches Client-Secret 15
Invalid user credentials Passwort, OTP fehlt oder Konto gesperrt (Log!) 10, 15
Account is not fully set up offene Required Action 10
unknown_error Fehler in Keycloak, z. B. LDAP weg – Log lesen 15
active:false bei Introspection fragender Client nicht in aud 3, 5
Audience "notes-api" fehlt (notes-api) Audience-Mapper fehlt 5, 15
email … isn't verified (oauth2-proxy) Broker ohne Trust email 11
Client secret must be re-entered … Token-URL eines IdP geändert 12
'--optimized' flag was used for first … startOptimized: false fehlt 14
curl: (60) SSL certificate problem Zertifikat oder CA passt nicht 12, 15