# OAuth Token Exchange mit Keycloak (RFC 8693): Tokens für KI-Agenten und MCP-Server einschränken

> Keycloak-Labor: Ein MCP-Server tauscht das Nutzer-Token gegen ein engeres für eine nachgelagerte API; drei ungültige Tauschversuche werden abgelehnt.

- URL: https://iamops.dev/de/keycloak-token-exchange-rfc-8693/
- Language: de
- Author: Argo
- Published: 2026-11-12
- Category: Labs
- Topics: Token Exchange, Keycloak, RFC 8693, MCP, KI-Agenten

## 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.

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](https://iamops.dev/de/mcp-server-no-token-passthrough/). 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>`.

```bash
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
```

![Terminalausgabe des Einrichtungsskripts, das den Realm agentlab, einen Nutzer, drei Clients und zwei Client Scopes anlegt; die Kennungen sind durch Platzhalter in spitzen Klammern ersetzt.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/03-setup.webp)

*Einrichtung. Das Skript legt den Realm, einen Testnutzer, die drei Clients und zwei Client Scopes an, die Audiences hinzufügen. Objekt-IDs sind durch Platzhalter ersetzt.*

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.

![Keycloak-Admin-Konsole, Capability-Konfiguration des Clients mcp-server, mit angehaktem Kontrollkästchen Standard Token Exchange.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/05-exchange-toggle.webp)

*Das Privileg. Standard Token Exchange ist nur beim Client mcp-server angehakt. Ein kompromittierter Agent-Client kann keine Tokens für andere APIs ausstellen.*

![Keycloak-Admin-Konsole, Client Scopes des Clients mcp-server, mit dem Scope aud-payments-api als Optional.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/06-client-scopes.webp)

*Die Audience. aud-payments-api ist für mcp-server optional, die nachgelagerte Audience muss also ausdrücklich angefordert werden.*

## Der Ablauf

Der Agent holt ein Nutzer-Token, dann tauscht der MCP-Server es. Die zentrale Anfrage ist ein einziger Aufruf des Token-Endpunkts:

```bash
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"
```

![Terminalausgabe mit dem Vergleich von dekodiertem Nutzer-Token und getauschtem Token. Die Audience wechselt von mcp-server und account zu payments-api, azp von agent zu mcp-server, expires_in ist 300, es gibt weder Refresh Token noch act-Claim.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/07-exchange.webp)

*Vorher und nachher. Gleicher Nutzer, neue Audience (payments-api), neue autorisierte Partei (mcp-server), 300 Sekunden Lebensdauer, kein Refresh Token. Die Nutzerkennung ist durch einen Platzhalter ersetzt.*

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.

![Terminalausgabe von drei abgelehnten Tauschversuchen: ein Client ohne aktivierten Token Exchange, eine Audience, für die der MCP-Server keinen Scope hat, und die Anforderung eines Refresh Tokens; jeder liefert invalid_request.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/08-negative.webp)

*Drei Ablehnungen. A: ein Client ohne das Tauschprivileg. B: eine Audience, für die der MCP-Server keinen Scope hat. C: ein Refresh Token. Alle liefern invalid_request. Client Secrets sind durch Platzhalter ersetzt.*

## 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](https://iamops.dev/de/tools/pkce/).
- **Der `aud`-Claim kann mehr auflisten als erwartet.** Bei der Introspektion des getauschten Tokens erschienen die Zahlungs-API und `account`. 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 Sie `azp` selbst in den Logs.

## Sicherheitserkenntnisse

1. Token Exchange ist ein Privileg. Vergeben Sie es nur an den einen Client, der es braucht.
2. Machen Sie die nachgelagerte Audience explizit und optional, damit getauschte Tokens standardmäßig eng bleiben.
3. Geben Sie in einem Tausch nie Refresh Tokens aus. Der Server des Labors lehnt sie ab.
4. Ein Dienst sollte Tokens ablehnen, die nicht für ihn ausgestellt wurden, und pro nachgelagerter API tauschen, nie das Token des Nutzers weiterreichen.
5. 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** `env.sh` (bash)

```bash
# 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="alice@example.com"
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"
```

### Schritt 1: Keycloak 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

`start-keycloak.sh` (bash)

```bash
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**

```text
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 2: Realm, 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

`kc-lab.sh` (bash)

```bash
#!/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"
```

(bash)

```bash
chmod +x kc-lab.sh && ./kc-lab.sh
```

**Erwartete Ausgabe**

```text
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 3: Das 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

`user-token.sh` (bash)

```bash
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**

```json
--- 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 4: Als 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

`exchange.sh` (bash)

```bash
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**

```json
{
  "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 5: Drei 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

`refusals.sh` (bash)

```bash
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**

```text
# 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 6: Aufrä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

`cleanup.sh` (bash)

```bash
# 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**

```text
000
```


## Sources

- [RFC 8693: OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693)
- [Keycloak documentation: Configuring and using token exchange](https://www.keycloak.org/securing-apps/token-exchange)
- [AWS What's New, 12 Nov 2026: Amazon Cognito now supports OAuth 2.0 token exchange](https://aws.amazon.com/about-aws/whats-new/2026/11/cognito-token-exchange/)
- [WorkOS changelog: Token exchange for WorkOS Connect](https://workos.com/changelog/token-exchange-for-workos-connect)
- [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://www.rfc-editor.org/rfc/rfc9700)
