Kurz gesagt
- Der Token Exchange nach RFC 8693 lässt einen MCP-Server das Nutzer-Token gegen ein engeres für genau eine nachgelagerte API tauschen.
- In Keycloak wird er pro Client aktiviert, und die nachgelagerte Audience ist ein optionaler Scope.
- Das getauschte Token behält den Nutzer als Subject, trägt nur die nachgelagerte Audience, lebt 300 Sekunden und enthält kein Refresh Token.
- Drei ungültige Tauschversuche werden abgelehnt: ein Client ohne das Recht, eine Audience ohne Scope und die Anforderung eines Refresh Tokens.
- In diesem Aufbau gibt es keinen act-Claim; der handelnde Client erscheint nur als Authorized Party.
Dieses Lab nachbauen
Dieses Lab habe ich so geschrieben, dass Sie es selbst nachbauen können. Jeder Schritt enthält die Befehle zum Kopieren und die Ausgabe, die ich bekommen habe, und Sie können ihn als erledigt abhaken. Die Haken bleiben nur in diesem Browser.
Kopiert einen fertigen Prompt für Claude Code, Cursor, Codex oder einen anderen Coding-Agenten. Nur für Testumgebungen.
Prompt anzeigen
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: OAuth Token Exchange mit Keycloak (RFC 8693): Tokens für KI-Agenten und MCP-Server einschränken Read the whole lab here (Markdown): https://iamops.dev/de/keycloak-token-exchange-rfc-8693.md What the lab needs before the first step: - Java 21 (for example Eclipse Temurin), curl, jq and unzip - Port 8080 free; keep this terminal open and use a second one for the next steps - Values I have to set myself (the lab uses placeholders): <ADMIN_PASSWORD>, <ALICE_PASSWORD>, <AGENT_CLIENT_SECRET>, <MCP_SERVER_CLIENT_SECRET>, <PAYMENTS_API_CLIENT_SECRET> How I want you to work: 1. Read the lab from start to finish first (each step lists its own prerequisites). Then check that the prerequisites are in place and that the tool versions match what the lab expects. Tell me what is missing before you run anything. 2. Run one step at a time. Before each command, show it to me and say in a sentence what it does. 3. Ask me before anything that costs money, creates cloud resources, touches a real tenant or account, or deletes anything. Wait for my answer. 4. Use the placeholders from the lab. Never paste real secrets, tokens or production identities into a command, a file or this chat. If a value is needed, tell me where to set it myself. 5. After each step, compare the output with the expected output in the lab. If it does not match, stop and tell me what differs. Do not carry on or invent a fix without asking me. 6. At the end, report what passed, what failed and which cleanup you did. Then offer to tick the steps off for me. The lab page keeps ticks only in my browser, so if you cannot do that, list the steps I should tick. This lab is for test environments only. Do not run it against production, or against a tenant or account that holds real data or real users. You may answer in my language.
Am 12. November 2026 hat Amazon Cognito OAuth 2.0 Token Exchange (RFC 8693) eingeführt, wenige Tage nach WorkOS Connect. Entra bietet seit Jahren einen eigenen On-Behalf-of-Ablauf. Das Muster ist inzwischen bei den großen Identity-Providern verbreitet: Ein Dienst, der für einen Nutzer handelt, tauscht dessen Token gegen ein neues Token, das enger gefasst, an genau einen Empfänger (Audience) gebunden und kurzlebig ist, statt das ursprüngliche weiterzureichen. Ich habe es gegen ein lokales Keycloak laufen lassen und notiert, was der Server tat.
Dieses Labor führt das Muster auf einem Laptop mit Keycloak aus, einem quelloffenen Autorisierungsserver. So sieht man genau, was sich im Token ändert und was der Server ablehnt.
Was das Labor zeigt#
Ein KI-Agent meldet den Nutzer an und hält ein Token für einen MCP-Server. Der MCP-Server muss für diesen Nutzer eine Zahlungs-API aufrufen, darf das Token des Agenten aber nicht weiterreichen. Stattdessen legt er es dem Autorisierungsserver vor und bittet um ein Token nur für die Zahlungs-API.
Das Labor verwendet drei Clients in einem Realm:
| Client | Rolle | Darf Tokens tauschen? |
|---|---|---|
agent |
Erhält das Token des Nutzers (Password Grant, nur Labor-Abkürzung) | Nein |
mcp-server |
Tauscht das Token des Nutzers | Ja |
payments-api |
Nur eine Audience, die nachgelagerte API | Nein |
Einrichtung#
Keycloak 26.8.2 lief aus der Zip-Distribution mit Java 21 im Entwicklungsmodus, nach frischem Entpacken. Der Entwicklungsmodus ist nur für Labore gedacht. Die Passwörter sind Wegwerfwerte; in diesem Beitrag erscheinen sie als <lab-password> und <client-secret>.
export KC_BOOTSTRAP_ADMIN_USERNAME=admin KC_BOOTSTRAP_ADMIN_PASSWORD=<lab-password>
keycloak-26.8.2/bin/kc.sh start-dev --http-port 8080
./kc-lab.sh # creates realm agentlab, user alice, the three clients and two audience scopes
In der Admin-Konsole tragen zwei Einstellungen das Design. Nur mcp-server hat Standard Token Exchange aktiviert, und die nachgelagerte Audience ist ein optionaler Scope, wird also nur hinzugefügt, wenn der Tausch sie anfordert.


Der Ablauf#
Der Agent holt ein Nutzer-Token, dann tauscht der MCP-Server es. Die zentrale Anfrage ist ein einziger Aufruf des Token-Endpunkts:
curl -s -u mcp-server:<client-secret> \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$USER_AT" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
-d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL"
Vergleicht man die beiden Tokens: Das Subject bleibt gleich, die Audience ist jetzt nur noch die Zahlungs-API, die autorisierte Partei (azp) nennt den MCP-Server, die Lebensdauer beträgt 300 Sekunden und es kommt kein Refresh Token zurück. Es gibt keinen act-Claim: Die Delegationsunterstützung von Keycloak ist eine Vorschaufunktion, die standardmäßig ausgeschaltet ist; der Akteur erscheint also nur als azp.
Absichtlich scheitern lassen#
Drei Tauschversuche müssen abgelehnt werden. Prüfen Sie dieselben drei bei jedem Identity-Provider, bevor Sie ihm die Delegation für Agenten anvertrauen.

Stolperfallen#
- Der Password Grant ist eine Abkürzung. Das Labor nutzt ihn nur, um schnell ein Nutzer-Token zu bekommen. RFC 9700 und OAuth 2.1 schließen ihn für echte Clients aus; verwenden Sie den Authorization-Code-Flow mit PKCE.
- Der
aud-Claim kann mehr auflisten als erwartet. Bei der Introspektion des getauschten Tokens erschienen die Zahlungs-API undaccount. Verstehen Sie das, bevor Sie sich auf Audience-Prüfungen verlassen. - Die Reihenfolge der Scopes schwankt von Lauf zu Lauf; vergleichen Sie Scope-Zeichenketten daher nicht wörtlich.
- Standardmäßig kein
act-Claim. Braucht Ihr Audit den Akteur, planen Sie die Vorschaufunktion für Delegation ein oder verknüpfen Sieazpselbst in den Logs.
Sicherheitserkenntnisse#
- Token Exchange ist ein Privileg. Vergeben Sie es nur an den einen Client, der es braucht.
- Machen Sie die nachgelagerte Audience explizit und optional, damit getauschte Tokens standardmäßig eng bleiben.
- Geben Sie in einem Tausch nie Refresh Tokens aus. Der Server des Labors lehnt sie ab.
- Ein Dienst sollte Tokens ablehnen, die nicht für ihn ausgestellt wurden, und pro nachgelagerter API tauschen, nie das Token des Nutzers weiterreichen.
- Prüfen Sie, was Ihr Audit-Trail rekonstruieren kann. Erscheint der Akteur nur als
azp, muss eine Logzeile Nutzer, Agent und nachgelagerte Audience verbinden.
Was nicht ausgeführt wurde#
Nicht ausgeführt wurden die Docker-Variante, die Zusatzaufgaben (Refresh Tokens im Standard-Tausch, Introspektion durch die nachgelagerte API) und die Vorschaufunktion für Delegation, die act hinzufügen würde. Das Labor verwendete nur Wegwerfkonten. Für dieses Labor wird keine Aufzeichnung veröffentlicht.
Die Terminalbilder wurden aus der gespeicherten Ausgabe des Laufs erzeugt; Kennungen und Geheimnisse sind durch Platzhalter ersetzt. Die Keycloak-Screenshots zeigen nur Testobjekte.
Dieses Lab nachbauen#
Alles, was Sie brauchen, um dieses Lab in etwa 45 Minuten auf einem Laptop auszuführen: ein lokales Keycloak, ein Skript für den Realm, eines für den Austausch und drei, die scheitern müssen. Öffnen Sie jeden Schritt, kopieren Sie die Blöcke und vergleichen Sie Ihre Ausgabe mit der erwarteten.
Jeder Wert in spitzen Klammern ist ein Platzhalter für Ihre Testumgebung. Nichts auf dieser Seite ist eine echte Kennung oder ein echtes Geheimnis.
Variablen einmal setzen
# Paste into every terminal you use for this lab. Replace each <PLACEHOLDER> with a throwaway value of your own.
export KC_VERSION="26.8.2"
export KC_URL="http://localhost:8080"
export KC_REALM="agentlab"
export KC_ADMIN_USER="admin"
export KC_ADMIN_PASSWORD='<ADMIN_PASSWORD>'
export ALICE_EMAIL="[email protected]"
export ALICE_PASSWORD='<ALICE_PASSWORD>'
export AGENT_SECRET='<AGENT_CLIENT_SECRET>'
export MCP_SECRET='<MCP_SERVER_CLIENT_SECRET>'
export PAYMENTS_SECRET='<PAYMENTS_API_CLIENT_SECRET>'
export TOKEN_URL="$KC_URL/realms/$KC_REALM/protocol/openid-connect/token" 0 von 6 Schritten erledigt
Schritt 1Keycloak im Entwicklungsmodus starten
Ziel. Starten Sie einen lokalen Autorisierungsserver unter Ihrer Kontrolle, um zu sehen, was der Token-Austausch im Token ändert.
Voraussetzungen
- Java 21 (zum Beispiel Eclipse Temurin), curl, jq und unzip
- Port 8080 frei; lassen Sie dieses Terminal offen und nutzen Sie für die nächsten Schritte ein zweites
curl -LO "https://github.com/keycloak/keycloak/releases/download/$KC_VERSION/keycloak-$KC_VERSION.zip"
unzip -q "keycloak-$KC_VERSION.zip"
export KC_BOOTSTRAP_ADMIN_USERNAME="$KC_ADMIN_USER" KC_BOOTSTRAP_ADMIN_PASSWORD="$KC_ADMIN_PASSWORD"
"keycloak-$KC_VERSION/bin/kc.sh" start-dev --http-port 8080 Erwartete Ausgabe
Running the server in development mode. DO NOT use this configuration in production.
INFO [org.keycloak.services] (main) KC-SERVICES0077: Created temporary admin user with username admin
INFO [io.quarkus] (main) Keycloak 26.8.2 on JVM (powered by Quarkus 3.40.1.1) started in 8.418s. Listening on: http://localhost:8080
INFO [io.quarkus] (main) Profile dev activated. Schritt 2Realm, Benutzer und drei Clients anlegen
Ziel. Bauen Sie den Realm agentlab mit Benutzer alice und drei Clients: agent erhält das Benutzer-Token, mcp-server darf es tauschen, payments-api ist nur eine Audience.
Voraussetzungen
- Schritt 1 abgeschlossen, Keycloak läuft; die Variablen vom Anfang dieses Abschnitts in diesem zweiten Terminal gesetzt
- Im Ordner ausführen, der das Keycloak-Verzeichnis enthält
#!/usr/bin/env bash
# Realm, user, three clients and two audience scopes. Lab only: throwaway secrets.
set -euo pipefail
KCADM="keycloak-$KC_VERSION/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
$KCADM create realms -s realm="$KC_REALM" -s enabled=true
$KCADM create users -r "$KC_REALM" -s username=alice -s enabled=true -s email="$ALICE_EMAIL" -s emailVerified=true -s firstName=Alice -s lastName=Lab
$KCADM set-password -r "$KC_REALM" --username alice --new-password "$ALICE_PASSWORD"
# Downstream API: only an audience
$KCADM create clients -r "$KC_REALM" -s clientId=payments-api -s publicClient=false -s secret="$PAYMENTS_SECRET" -s standardFlowEnabled=false -s directAccessGrantsEnabled=false
# MCP server: confidential, allowed to exchange tokens
$KCADM create clients -r "$KC_REALM" -s clientId=mcp-server -s publicClient=false -s secret="$MCP_SECRET" -s standardFlowEnabled=false -s directAccessGrantsEnabled=false -s 'attributes."standard.token.exchange.enabled"=true'
# Agent: gets the user token (password grant only because this is a lab)
$KCADM create clients -r "$KC_REALM" -s clientId=agent -s publicClient=false -s secret="$AGENT_SECRET" -s directAccessGrantsEnabled=true -s standardFlowEnabled=true -s 'redirectUris=["http://localhost:6274/*"]'
# Client scopes that add audiences
for AUD in mcp-server payments-api; do
SID=$($KCADM create client-scopes -r "$KC_REALM" -s name=aud-$AUD -s protocol=openid-connect -s 'attributes."include.in.token.scope"=true' -i)
$KCADM create client-scopes/$SID/protocol-mappers/models -r "$KC_REALM" -s name=aud-$AUD -s protocol=openid-connect -s protocolMapper=oidc-audience-mapper -s "config.\"included.client.audience\"=$AUD" -s 'config."access.token.claim"=true'
done
AGENT=$($KCADM get clients -r "$KC_REALM" -q clientId=agent --fields id --format csv --noquotes)
MCP=$($KCADM get clients -r "$KC_REALM" -q clientId=mcp-server --fields id --format csv --noquotes)
S1=$($KCADM get client-scopes -r "$KC_REALM" --fields id,name --format csv --noquotes | awk -F, '$2=="aud-mcp-server"{print $1}')
S2=$($KCADM get client-scopes -r "$KC_REALM" --fields id,name --format csv --noquotes | awk -F, '$2=="aud-payments-api"{print $1}')
# agent always gets the mcp-server audience; mcp-server may ask for payments-api as an optional scope
$KCADM update clients/$AGENT/default-client-scopes/$S1 -r "$KC_REALM"
$KCADM update clients/$MCP/optional-client-scopes/$S2 -r "$KC_REALM"
echo "realm $KC_REALM ready" chmod +x kc-lab.sh && ./kc-lab.sh Erwartete Ausgabe
Logging into http://localhost:8080 as user admin of realm master
Created new realm with id 'agentlab'
Created new user with id '<user-id>'
Created new client with id '<client-id>'
Created new client with id '<client-id>'
Created new client with id '<client-id>'
Created new model with id '<scope-id>'
Created new model with id '<scope-id>'
realm agentlab ready Schritt 3Das Benutzer-Token als Agent holen
Ziel. Holen Sie das Token, das der MCP-Server erhält, und dekodieren Sie es, damit Sie eine Basis zum Vergleich mit dem getauschten Token haben.
Voraussetzungen
- Schritt 2 abgeschlossen (Realm agentlab existiert)
- Der Password Grant ist nur eine Lab-Abkürzung; echte Clients nutzen den Authorization-Code-Flow mit PKCE
jwtp() { cut -d. -f2 | tr '_-' '/+' | awk '{l=length($0)%4; if(l==2)$0=$0"=="; else if(l==3)$0=$0"="; print}' | base64 -d 2>/dev/null; }
USER_AT=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
-d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
echo "--- user token seen by mcp-server"
echo "$USER_AT" | jwtp | jq '{iss,aud,azp,sub,preferred_username,scope}' Erwartete Ausgabe
--- user token seen by mcp-server
{
"iss": "http://localhost:8080/realms/agentlab",
"aud": ["mcp-server", "account"],
"azp": "agent",
"sub": "<user-id>",
"preferred_username": "alice",
"scope": "openid profile aud-mcp-server email"
} Schritt 4Als MCP-Server tauschen (RFC 8693)
Ziel. Tauschen Sie das Benutzer-Token gegen ein engeres, das nur für die Payments-API bestimmt ist, und prüfe, was sich geändert hat.
Voraussetzungen
- Schritt 3 im selben Terminal abgeschlossen, damit USER_AT gesetzt ist
curl -s -u "mcp-server:$MCP_SECRET" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$USER_AT" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
-d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL" > exch.json
jq '{issued_token_type,token_type,expires_in,scope, refresh: (has("refresh_token"))}' exch.json
echo "--- exchanged token for payments-api"
jq -r .access_token exch.json | jwtp | jq '{iss,aud,azp,sub,preferred_username,scope,act}' Erwartete Ausgabe
{
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 300,
"scope": "aud-payments-api profile email",
"refresh": false
}
--- exchanged token for payments-api
{
"iss": "http://localhost:8080/realms/agentlab",
"aud": "payments-api",
"azp": "mcp-server",
"sub": "<user-id>",
"preferred_username": "alice",
"scope": "aud-payments-api profile email",
"act": null
} Schritt 5Drei Austausche absichtlich scheitern lassen
Ziel. Prüfen Sie die drei Ablehnungen, die ein kompromittiertes Glied bremsen: kein Recht, kein Audience-Scope, kein Refresh-Token.
Voraussetzungen
- Schritt 3 im selben Terminal abgeschlossen, damit USER_AT gesetzt ist
- Tokens leben fünf Minuten; bei einem Token-Fehler zuerst Schritt 3 wiederholen
X=(-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token="$USER_AT"
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token)
echo "# A: a client without token exchange enabled"
curl -s -u "payments-api:$PAYMENTS_SECRET" "${X[@]}" -d audience=mcp-server "$TOKEN_URL" | jq .
echo "# B: an audience mcp-server has no scope for"
curl -s -u "mcp-server:$MCP_SECRET" "${X[@]}" -d audience=agent "$TOKEN_URL" | jq .
echo "# C: ask for a refresh token"
curl -s -u "mcp-server:$MCP_SECRET" "${X[@]}" -d audience=payments-api -d scope=aud-payments-api \
-d requested_token_type=urn:ietf:params:oauth:token-type:refresh_token "$TOKEN_URL" | jq . Erwartete Ausgabe
# A: a client without token exchange enabled
{
"error": "invalid_request",
"error_description": "Standard token exchange is not enabled for the requested client"
}
# B: an audience mcp-server has no scope for
{
"error": "invalid_request",
"error_description": "Requested audience not available: agent"
}
# C: ask for a refresh token
{
"error": "invalid_request",
"error_description": "requested_token_type unsupported"
} Schritt 6Aufräumen
Ziel. Stoppen Sie Keycloak und löschen Sie alles, was das Lab erzeugt hat, einschließlich der heruntergeladenen Distribution und der Datei mit dem getauschten Token.
Voraussetzungen
- Nichts anderes nutzt Port 8080 oder das Keycloak-Verzeichnis
# Stop Keycloak: press Ctrl+C in the first terminal, or:
pkill -f "keycloak-$KC_VERSION" || true
rm -rf "keycloak-$KC_VERSION" "keycloak-$KC_VERSION.zip" kc-lab.sh exch.json
unset KC_ADMIN_PASSWORD ALICE_PASSWORD AGENT_SECRET MCP_SECRET PAYMENTS_SECRET USER_AT
# check: nothing listens on port 8080 any more
curl -s -o /dev/null -w "%{http_code}\n" "$KC_URL/" Erwartete Ausgabe
000 Quellen#
Diesen Beitrag diskutieren#
Hat es dir geholfen? Teile es und sag mir, was du denkst.
Dieser Beitrag als Markdown · RSS · JSON feed
Neue Beiträge per E-Mail
Eine E-Mail pro Woche mit neuen Beiträgen und Labs. Jederzeit abbestellbar.
Ihre Adresse wird bei Kit gespeichert, dem Dienst, der die E-Mails versendet. Details