Tag 3: OIDC und Tokens
Ziel: Einen Client anlegen, Tokens auf drei Wegen holen und lesen, die Endpunkte von OpenID Connect benutzen und den Authorization Code Flow mit PKCE von Hand durchspielen. · Dauer: ca. 75 min · Voraussetzung: Tag 2
Briefing
- Ein Client ist eine Anwendung, die Keycloak kennt. Confidential heißt: Sie hat ein Secret und läuft auf einem Server.
- Flows: Authorization Code mit PKCE für alles mit Browser, Client Credentials für Maschinen, Password (Direct Access Grant) nur für Tests.
- Ein Login liefert drei Tokens: Access Token (für APIs), ID Token (für die Anwendung: wer ist angemeldet), Refresh Token (für neue Access Tokens).
- Keycloak signiert mit RS256; die öffentlichen Schlüssel stehen im
JWKS
(
/protocol/openid-connect/certs).
Browser ─► /auth?…&code_challenge=… ─► Login ─► Redirect mit ?code=…
Anwendung ─► /token code + code_verifier + Secret ─► Access, ID, Refresh Token
API ─► prüft Signatur mit dem JWKS, ohne Keycloak zu fragen
Drill 1: Der Client notes-cli
source ~/kc-lab/setup/env.sh
mkdir -p ~/kc-lab/tag03 && cd ~/kc-lab/tag03
kclogin
kcadm create clients -r lab -s clientId=notes-cli -s enabled=true \
-s publicClient=false -s secret=lab-client-secret-123 \
-s standardFlowEnabled=true -s directAccessGrantsEnabled=true \
-s serviceAccountsEnabled=true -s 'redirectUris=["http://localhost:9999/*"]'
kcadm get clients -r lab -q clientId=notes-cli --fields clientId,publicClient,\
standardFlowEnabled,directAccessGrantsEnabled,serviceAccountsEnabledErwartet (gekürzt):
Logging into http://localhost:8080 as user kcadmin of realm master
Created new client with id '9e9423dd-…'
[ {
"clientId" : "notes-cli",
"publicClient" : false,
"standardFlowEnabled" : true,
"directAccessGrantsEnabled" : true,
"serviceAccountsEnabled" : true
} ]
Drei Flows an einem Client, nur fürs Labor. In Produktion bekommt jede Anwendung einen eigenen Client mit genau dem einen Flow, den sie braucht.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ein Token holen und lesen
token aus env.sh nutzt den Password Grant.
Erst die ganze Antwort, gekürzt:
OIDC=$KC_URL/realms/lab/protocol/openid-connect
R=$(curl -s -d grant_type=password -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 -d username=anna -d password=lab-user-pw-123 \
-d scope=openid $OIDC/token)
echo "$R" | jq -c 'with_entries(if (.key | test("token$")) then
.value = (.value | .[0:12] + "…") else . end)'
TOKEN=$(echo "$R" | jq -r .access_token)Erwartet (gekürzt):
{"access_token":"eyJhbGciOiJS…","expires_in":120,"refresh_expires_in":1800,
"refresh_token":"eyJhbGciOiJI…","token_type":"Bearer","id_token":"eyJhbGciOiJS…",
"not-before-policy":0,"session_state":"…","scope":"openid profile email"}
120 Sekunden gilt das Access Token (Challenge aus Tag 1), 30 Minuten das Refresh Token. Jetzt hinein:
echo "$TOKEN" | jq -R 'split(".")[0] | @base64d | fromjson'
jwt "$TOKEN" | jq '{iss, aud, azp, typ, preferred_username, email, scope,
roles: .realm_access.roles, gueltig: (.exp - .iat)}'Erwartet (gekürzt, Werte weichen bei dir ab):
{
"alg": "RS256",
"typ": "JWT",
"kid": "7W_UiON_Ted47k_XNQtdRHxugodLEjknJMcM9x8Up90"
}
{
"iss": "http://kc.192.168.64.7.sslip.io:8080/realms/lab",
"aud": "account",
"azp": "notes-cli",
"typ": "Bearer",
"preferred_username": "anna",
"email": "[email protected]",
"scope": "openid profile email",
"roles": [
"offline_access",
"notes-lesen",
"default-roles-lab",
"uma_authorization",
"notes-schreiben"
],
"gueltig": 120
}
iss ist der Name aus KC_URL,
azp der Client, der das Token geholt hat, und unter
realm_access.roles stehen die effektiven Rollen aus Tag 2.
aud: account merkst du dir für Drill 4.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Schlüssel und Benutzerdaten
curl -s $OIDC/certs | jq -r '.keys[] | [.kid, .alg, .use] | @tsv'
curl -s -H "Authorization: Bearer $TOKEN" $OIDC/userinfo | jq -c .Erwartet (gekürzt):
7W_UiON_Ted47k_XNQtdRHxugodLEjknJMcM9x8Up90 RS256 sig
RKshEJsdujnto2iWso-r2Z4n4V325acUNKeZdPoC0Lw RSA-OAEP enc
{"sub":"86ed1f4c-…","email_verified":true,"name":"Anna Lab","preferred_username":"anna",
"given_name":"Anna","family_name":"Lab","email":"[email protected]"}
Die kid des Signaturschlüssels ist dieselbe wie im
Header des Tokens. Genau so findet notes-api den passenden Schlüssel
(Tag 0, Challenge). userinfo liefert die Profildaten zum
Token.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Introspection und die Audience
Eine API kann Keycloak auch fragen, ob ein Token noch gültig ist:
curl -s -u notes-cli:lab-client-secret-123 -d token=$TOKEN $OIDC/token/introspect \
| jq -c '{active}'
docker compose -f ~/kc-lab/keycloak/compose.yaml logs --since 1m keycloak 2>&1 \
| grep -o 'reason="[^"]*"' | tail -1Erwartet:
{"active":false}
reason="Client 'notes-cli' is not in the token audience"
Das Token ist frisch, und trotzdem active: false.
Keycloak 26 beantwortet die Introspection nur, wenn der fragende Client
in der Audience (aud) des Tokens steht.
Hier steht nur account. Eine Audience fürs eigene API
trägst du in Tag 5 nach. Den Grund verrät nur das Event im Log, nicht
die Antwort selbst.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Maschinen und Erneuerung
Ein Dienst ohne Benutzer holt sich ein Token mit seinem eigenen Secret:
CC=$(curl -s -d grant_type=client_credentials -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 $OIDC/token | jq -r .access_token)
jwt "$CC" | jq -c '{preferred_username, azp, roles: .realm_access.roles}'Erwartet:
{"preferred_username":"service-account-notes-cli","azp":"notes-cli","roles":
["offline_access","default-roles-lab","uma_authorization"]}
Der Service Account ist ein eigener Benutzer mit eigenen Rollen. Und wenn ein Access Token abläuft, tauscht die Anwendung das Refresh Token gegen ein neues:
RT=$(echo "$R" | jq -r .refresh_token)
N=$(curl -s -d grant_type=refresh_token -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 -d refresh_token=$RT $OIDC/token)
echo "$N" | jq -c '{expires_in, refresh_expires_in}'
curl -s -o /dev/null -w 'logout %{http_code}\n' -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 \
-d refresh_token=$(echo "$N" | jq -r .refresh_token) $OIDC/logout
curl -s -d grant_type=refresh_token -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 \
-d refresh_token=$(echo "$N" | jq -r .refresh_token) $OIDC/token | jq -c .Erwartet:
{"expires_in":120,"refresh_expires_in":1800}
logout 204
{"error":"invalid_grant","error_description":"Session not active"}
Logout beendet die Sitzung in Keycloak; das Refresh Token ist danach
wertlos. Das schon ausgegebene Access Token bleibt bis zu seinem
exp gültig, wenn eine API es nur per Signatur prüft. Darum
sind kurze Access Tokens wichtig.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Authorization Code mit PKCE von Hand
So meldet sich eine Webanwendung an. Erst ein zufälliger Code Verifier und daraus die Code Challenge (SHA-256, Base64url):
V=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
C=$(printf %s "$V" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
echo "${#V} ${#C}"
echo "$OIDC/auth?client_id=notes-cli&response_type=code&scope=openid\
&redirect_uri=http://localhost:9999/cb&code_challenge=$C&code_challenge_method=S256\
&state=xyz"Erwartet (gekürzt):
63 43
http://kc.192.168.64.7.sslip.io:8080/realms/lab/protocol/openid-connect/auth?client_id=…
Öffne die URL im Browser des Laptops und melde dich als
anna an. Keycloak leitet auf
http://localhost:9999/cb?… um; dort läuft nichts, der
Browser meldet einen Fehler. Wichtig ist die Adresszeile. Kopier sie
zügig (der Code gilt eine Minute) in die VM:
CB='http://localhost:9999/cb?state=xyz&session_state=…&code=…'
echo "$CB" | grep -o '[?&]state=[^&]*'
CODE=$(echo "$CB" | grep -o 'code=[^&]*' | cut -d= -f2)
tausch() {
curl -s -d grant_type=authorization_code -d client_id=notes-cli \
-d client_secret=lab-client-secret-123 -d code=$CODE \
-d redirect_uri=http://localhost:9999/cb -d code_verifier="$1" $OIDC/token
}
tausch "$V" | jq -c '{token_type, expires_in, scope, id_token: (.id_token != null)}'
tausch "$V" | jq -c .Erwartet:
?state=xyz
{"token_type":"Bearer","expires_in":120,"scope":"openid profile email","id_token":true}
{"error":"invalid_grant","error_description":"Code not valid"}
state kommt unverändert zurück; die Anwendung prüft
damit, dass die Antwort zu ihrer Anfrage gehört. Der Code gilt genau
einmal. Und ohne den richtigen Verifier hilft ein abgefangener Code
nichts:
CB='…' # neuer Login, neue Adresszeile
CODE=$(echo "$CB" | grep -o 'code=[^&]*' | cut -d= -f2)
tausch falsch-falsch-falsch-falsch-falsch-falsch-falsch-1234 | jq -c .Erwartet:
{"error":"invalid_grant","error_description":"PKCE verification failed: Code mismatch"}
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
jwt "$(token)" | jq -r .preferred_usernameErwartet: token aus env.sh
funktioniert.
anna
jwt "$(token ben lab-user-pw-456)" \
| jq -c '.realm_access.roles | map(select(startswith("notes")))'Erwartet: bens Token enthält nur die Leserolle.
["notes-lesen"]
curl -s $OIDC/certs | jq '[.keys[] | select(.use == "sig")] | length'Erwartet: ein Signaturschlüssel.
1
Challenge
Zeig, dass ein Access Token nach Ablauf bei userinfo
scheitert, obwohl seine Signatur weiter stimmt.
Hinweis: Die Lebensdauer kennst du;
userinfo fragt die Sitzung in Keycloak.
Lösung
T=$(token)
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $T" $OIDC/userinfo
sleep 125
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $T" $OIDC/userinfoErwartet:
200
401
Keycloak prüft bei userinfo auch exp und
antwortet mit 401 ohne Text; den Grund nennt der Header
WWW-Authenticate (curl -i). Eine API, die
selbst prüft, muss das ebenso tun; notes-api lässt höchstens 30 Sekunden
Uhrenabweichung zu.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Kein Password Grant: OAuth 2.1 streicht ihn. Anwendungen mit Benutzern nehmen den Authorization Code Flow mit PKCE, Maschinen Client Credentials.
- Public Clients (Single-Page-Apps, Mobile) haben kein Secret; dort ist PKCE die einzige Absicherung des Codes und Pflicht.
- Tokens im Browser gehören nicht in
localStorage. Besser: ein Backend hält die Tokens, der Browser nur ein Session-Cookie (Tag 4 mit oauth2-proxy). - Signaturprüfung oder Introspection: Prüfen per JWKS
ist schnell und ohne Rundreise, erkennt aber kein Logout vor
exp. Introspection erkennt es und kostet pro Anfrage eine Rundreise zu Keycloak.