Zum Inhalt springen
Trainingslager IT-Trainingslager

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,serviceAccountsEnabled

Erwartet (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 -1

Erwartet:

{"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_username

Erwartet: 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/userinfo

Erwartet:

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.