Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: JWT mit Keycloak

Ziel: Keycloak als Aussteller von Tokens starten, Kong die Signatur prüfen lassen und eine Route bauen, die Schlüssel oder Token annimmt. · Dauer: ca. 75 min · Voraussetzung: Tag 5

Briefing

  • Ein JWT besteht aus Header, Payload und Signatur. Keycloak signiert mit seinem privaten RSA-Schlüssel (RS256), Kong prüft mit dem öffentlichen.
  • Das Plugin jwt sucht den passenden Schlüssel über den Claim iss (Aussteller). Der Schlüssel gehört zu einem Consumer, hier keycloak.
  • Der Consumer ist damit der Aussteller, nicht die Person. Wer genau im Token steht, sieht Kong OSS nicht (dazu Tag 11).
  • Mehrere Auth-Plugins an einer Route heißen und. Für oder gibt es den anonymen Consumer.
 notes-cli ──client_secret──► Keycloak :8180 ──► JWT (iss, exp, RS256)
 notes-cli ──Bearer JWT─────► Kong jwt ──iss?──► Consumer keycloak ──Schlüssel prüfen

Drill 1: Keycloak starten

source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag06 && cd ~/kong-lab/tag06
cp -R ~/kong-lab/code/keycloak ~/kong-lab/keycloak
grep -E 'image|KC_HOSTNAME|8180:' ~/kong-lab/keycloak/compose.yaml
jq '{realm, accessTokenLifespan, clients: [.clients[].clientId],
  users: [.users[].username]}' ~/kong-lab/keycloak/realm-lab.json
cd ~/kong-lab/keycloak && docker compose up -d --wait
docker compose logs keycloak | grep -E "imported|started in" | cut -c1-110

Erwartet (gekürzt, beim ersten Mal ein bis zwei Minuten):

    image: quay.io/keycloak/keycloak:26.8.1
      KC_HOSTNAME: http://localhost:8180   # fester Aussteller (iss) in jedem Token
      - "127.0.0.1:8180:8080"
{
  "realm": "lab",
  "accessTokenLifespan": 60,
  "clients": [
    "notes-cli"
  ],
  "users": [
    "anna"
  ]
}
 Container keycloak-keycloak-1 Healthy
keycloak-1  | … INFO  [org.keycloak.exportimport.util.ImportUtils] (main) Realm 'lab' i…
keycloak-1  | … INFO  [io.quarkus] (main) Keycloak 26.8.1 on JVM (powered by Quarkus 3.4

Keycloak läuft im Entwicklungsmodus mit dem Realm lab. KC_HOSTNAME sorgt dafür, dass jedes Token denselben Aussteller trägt, egal über welchen Weg es geholt wird. Tokens gelten 60 Sekunden, damit du in Drill 5 nicht lange warten musst.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Ein Token holen und lesen

env.sh bringt die Funktion token mit: Sie meldet den Client notes-cli mit seinem Secret an (Client Credentials) und gibt das Access Token aus.

cd ~/kong-lab/tag06
curl -s $KC/.well-known/openid-configuration | jq -r '.issuer, .jwks_uri'
TOKEN=$(token)
echo ${#TOKEN}
echo "$TOKEN" | jq -R 'split(".")[0] | @base64d | fromjson'
echo "$TOKEN" | jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d
  | fromjson | {iss, azp, preferred_username, exp}'

Erwartet (gekürzt, Werte weichen bei dir ab):

http://localhost:8180/realms/lab
http://localhost:8180/realms/lab/protocol/openid-connect/certs
1239
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "mxakh5-l1apcw4monopJzQpw44nxWRSJ5ZoSycxVeyA"
}
{
  "iss": "http://localhost:8180/realms/lab",
  "azp": "notes-cli",
  "preferred_username": "service-account-notes-cli",
  "exp": 1793535699
}

Header und Payload sind nur Base64, jeder kann sie lesen. Geschützt ist nichts davon, nur unverfälschbar: Die Signatur im dritten Teil passt nur zu genau diesem Inhalt.

Sicherheit: Ein Token ist ein Ausweis. Gib es nicht aus, häng es nicht in Tickets, und speichere es nur in Variablen wie $TOKEN.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Keycloak als Consumer

Kong braucht den öffentlichen Schlüssel des Realms als PEM. Keycloak liefert ihn als Base64; vier Zeilen machen ein PEM daraus:

PUB=$(curl -s $KC | jq -r .public_key)
{ echo "-----BEGIN PUBLIC KEY-----"; echo "$PUB" | fold -w 64
  echo "-----END PUBLIC KEY-----"; } > keycloak.pem
openssl pkey -pubin -in keycloak.pem -noout -text | head -1

Erwartet:

Public-Key: (2048 bit)

Damit baust du zwei Consumer: keycloak mit dem Schlüssel und der Gruppe schreiber, und gast für Drill 6.

cat > consumers-jwt.yaml <<EOF
consumers:
  - username: gast
    acls:
      - group: gast
  - username: keycloak
    acls:
      - group: schreiber
    jwt_secrets:
      - key: $KC
        algorithm: RS256
        secret: nur-fuer-hs256
        rsa_public_key: |
$(sed 's/^/          /' keycloak.pem)
EOF
sed -n '1,13p' consumers-jwt.yaml
deck file merge ~/kong-lab/kong/kong.yaml consumers-jwt.yaml -o m1.yaml
deck gateway validate m1.yaml && cp m1.yaml ~/kong-lab/kong/kong.yaml && kreload

Erwartet (gekürzt):

consumers:
  - username: gast
    acls:
      - group: gast
  - username: keycloak
    acls:
      - group: schreiber
    jwt_secrets:
      - key: http://localhost:8180/realms/lab
        algorithm: RS256
        secret: nur-fuer-hs256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
Kong reloaded

key muss exakt dem iss im Token entsprechen. secret braucht nur HS256; decK verlangt das Feld trotzdem, darum steht dort ein sprechender Platzhalter.

In der Oberfläche von Keycloak (Tunnel mit zusätzlich -L 8180:localhost:8180, dann http://localhost:8180, Benutzer admin, Passwort lab-admin-pw-123) findest du im Realm lab den Client notes-cli:

Der Client notes-cli im Realm lab

Unter Realm settings, Keys steht der RS256-Schlüssel, dessen öffentlichen Teil Kong jetzt kennt. Die Kid entspricht der aus dem Header in Drill 2.

Die Schlüssel des Realms lab mit dem RS256-Schlüssel

Fortschritt speichern? Kostenlos registrieren

Drill 4: Zwei Plugins heißt beides

whoami hat seit Tag 5 key-auth. Häng jwt dazu:

cp ~/kong-lab/code/tag06/*.yaml .
deck file add-plugins -s ~/kong-lab/kong/kong.yaml nur-jwt.yaml -o neu.yaml
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
TOKEN=$(token)
K='apikey: lab-key-anna-456'
curl -s -w ' %{http_code}\n' -H "$K" $PROXY/whoami
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $TOKEN" $PROXY/whoami \
  | tr -d '\n'; echo
curl -s -H "$K" -H "Authorization: Bearer $TOKEN" $PROXY/whoami \
  | jq -c '.headers | {"X-Consumer-Username"}'

Erwartet (gekürzt):

Kong reloaded
{"message":"Unauthorized"} 401
{  "message":"No API key found in request",  "request_id":"3ecee47f…"} 401
{"X-Consumer-Username":["anna"]}

Mit Schlüssel allein fehlt das Token, mit Token allein der Schlüssel: Jedes Plugin verlangt seins. Mit beiden kommst du durch, und key-auth (Priorität 1250) setzt den Consumer zuletzt, also anna.

Jetzt die Fehlerbilder von jwt. Ein Token, dessen Payload du veränderst, und ein Token, das kein JWT ist:

H=$(echo "$TOKEN" | cut -d. -f1); S=$(echo "$TOKEN" | cut -d. -f3)
P=$(echo "$TOKEN" | jq -cR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d
  | fromjson | .azp = "boese"' | base64 -w0 | tr '/+' '_-' | tr -d '=')
curl -s -w ' %{http_code}\n' -H "$K" -H "Authorization: Bearer $H.$P.$S" $PROXY/whoami
curl -s -w ' %{http_code}\n' -H "$K" -H 'Authorization: Bearer kaputt' $PROXY/whoami

Erwartet:

{"message":"Invalid signature"} 401
{"message":"Bad token; invalid JSON"} 401

Ein einziges geändertes Feld, und die Signatur passt nicht mehr.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Ablaufdatum

claims_to_verify: [exp] lässt Kong das Ablaufdatum prüfen. Das Token aus Drill 4 ist inzwischen älter. Warte, bis es sicher abgelaufen ist:

sleep 60
curl -s -w ' %{http_code}\n' -H "$K" -H "Authorization: Bearer $TOKEN" $PROXY/whoami

Erwartet:

{"exp":"token expired"} 401

Ohne claims_to_verify würde Kong abgelaufene Tokens annehmen, solange die Signatur stimmt. Kurze Lebensdauer plus Prüfung von exp begrenzt den Schaden eines gestohlenen Tokens.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Schlüssel oder Token

Schreiben soll mit annas Schlüssel oder einem Token aus Keycloak gehen. Der Trick: Beide Plugins bekommen anonymous: gast. Scheitert eins, ist der Consumer gast statt einer Ablehnung, und erst die ACL entscheidet:

grep -v '^#' oder.yaml | sed -n '1,17p'
deck file add-plugins -s ~/kong-lab/kong/kong.yaml oder.yaml -o neu.yaml
deck gateway diff neu.yaml | grep -E '^(creating|updating|deleting)'
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload

Erwartet (gekürzt):

_format_version: "1.0"
add-plugins:
  - selectors:
      - $..routes[?(@.name=="notes-schreiben")]
      - $.services[?(@.name=="whoami")]
    overwrite: true
    plugins:
      - name: key-auth
        config:
          hide_credentials: true
          anonymous: gast
      - name: jwt
        config:
          anonymous: gast
          claims_to_verify: [exp]
  - selectors:
      - $.services[?(@.name=="whoami")]
Warning: import/export of basic-authcredentials using decK doesn't work due to hashing
of passwords in Kong.
updating plugin jwt for service whoami  {
creating plugin jwt for route notes-schreiben
updating plugin key-auth for route notes-schreiben  {
updating plugin key-auth for service whoami  {
creating plugin acl for service whoami
Kong reloaded

overwrite: true ersetzt die vorhandenen key-auth und jwt. Probier alle Wege:

TOKEN=$(token)
schreib() {
  curl -s -w ' %{http_code}\n' -X POST -H 'Content-Type: application/json' "$@" \
    -d '{"text":"Schlüssel oder Token"}' $PROXY/api/v1/notes | tr -d '\n'; echo
}
schreib
schreib -H "Authorization: Bearer $TOKEN"
schreib -H 'apikey: lab-key-anna-456'
schreib -H 'apikey: lab-key-ben-123'
schreib -H 'Authorization: Bearer kaputt'
curl -s -H "Authorization: Bearer $TOKEN" $PROXY/whoami \
  | jq -c '.headers | {"X-Consumer-Username", "X-Credential-Identifier"}'

Erwartet (gekürzt):

{  "message":"You cannot consume this service",  "request_id":"707fe21c…"} 403
{"id":"e017094b-…","text":"Schlüssel oder Token"} 201
{"id":"f8c827b2-…","text":"Schlüssel oder Token"} 201
{  "message":"You cannot consume this service",  "request_id":"6ab52218…"} 403
{  "message":"You cannot consume this service",  "request_id":"7790240e…"} 403
{"X-Consumer-Username":["keycloak"],"X-Credential-Identifier":["http://localhost:8180/r…

Token und Schlüssel gehen. Alles andere endet als gast und scheitert an der ACL mit 403, auch ein kaputtes Token. Der Preis von oder: Der Client erfährt nicht mehr, warum er abgelehnt wurde. Und das Backend sieht als Consumer keycloak, nicht den Namen aus dem Token.

Stand festhalten:

cd ~/kong-lab/kong
git add kong.yaml && git commit -qm "Tag 6: JWT von Keycloak, Schlüssel oder Token"
git log --oneline | head -1

Erwartet (der Hash weicht bei dir ab):

5d1e0a3 Tag 6: JWT von Keycloak, Schlüssel oder Token

Achtung: Ab heute enthält deine kong.yaml den öffentlichen Schlüssel deines Keycloak. Der Begleitcode kann sie darum nicht mehr fertig liefern; dein Git-Stand ist ab hier die Grundlage.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

curl -s $ADMIN/consumers | jq -r '.data[].username' | sort

Erwartet: vier Consumer.

anna
ben
gast
keycloak
curl -s $ADMIN/jwts | jq -r '.data[] | [.key, .algorithm] | @tsv'

Erwartet: ein Schlüssel für den Aussteller deines Realms.

http://localhost:8180/realms/lab    RS256
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H "Authorization: Bearer $(token)" \
  -H 'Content-Type: application/json' -d '{"text":"Kontrolle"}' $PROXY/api/v1/notes

Erwartet: Ein frisches Token darf schreiben.

201

Challenge

Hol ein Token für die Benutzerin anna statt für den Client (Password Grant, ihr Passwort ist lab-user-pw-123). Welchen Namen trägt das Token, welchen Consumer sieht das Backend, und warum unterscheiden sie sich?

Hinweis: grant_type=password mit username und password; der Client erlaubt das (directAccessGrantsEnabled).

Lösung

UTOKEN=$(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 \
  $KC/protocol/openid-connect/token | jq -r .access_token)
echo "$UTOKEN" | jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d
  | fromjson | {preferred_username, email}'
curl -s -H "Authorization: Bearer $UTOKEN" $PROXY/whoami \
  | jq -c '.headers | {"X-Consumer-Username"}'

Erwartet:

{
  "preferred_username": "anna",
  "email": "[email protected]"
}
{"X-Consumer-Username":["keycloak"]}

Im Token steht anna, beim Backend kommt keycloak an. Das Plugin jwt ordnet Tokens über iss einem Consumer zu, und alle Tokens dieses Realms haben denselben Aussteller. Den Namen aus dem Token ans Backend zu geben, ist die Aufgabe deines eigenen Plugins in Tag 11.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • openid-connect: Kong Enterprise bringt ein Plugin für OpenID Connect mit: Discovery, JWKS mit Schlüsselwechsel, Login im Browser, Scopes und Claims als Header. In OSS bleibt jwt mit festem Schlüssel.
  • Schlüsselwechsel: Rotiert Keycloak seinen RSA-Schlüssel, scheitern alle Tokens, bis Kong den neuen kennt. Plane den Wechsel: neuen Schlüssel zusätzlich eintragen, dann umstellen.
  • Keycloak in Produktion: nicht start-dev, sondern start mit Postgres, TLS und mehreren Instanzen; Tiefe im Buch „Keycloak zum Anfassen”.
  • Password Grant ist in OAuth 2.1 gestrichen. Für Personen gehört der Authorization Code Flow mit PKCE ins Frontend, für Maschinen Client Credentials.