# Downscoping beim Token Exchange für Agent-zu-Agent-Aufrufe erzwingen

> Keycloak-Labor für A2A-Agenten: Das Token, das B für C erhält, folgt den Scopes von B, nicht von A, ohne erzwungenes Downscoping. Lauf, Kontrolle, Abhilfe.

- URL: https://iamops.dev/de/enforce-downscoping-token-exchange-a2a/
- Language: de
- Author: Argo
- Published: 2026-11-20
- Category: Labs
- Topics: Token Exchange, Keycloak, A2A, RFC 8693, KI-Agenten

## Kurz gesagt

- Wenn Agent B für Agent A den Agenten C aufruft, tauscht B das Token von A gegen ein neues. In Keycloak 26.8.2 folgt der Scope dieses neuen Tokens den Scopes von B und nicht dem Token von A, solange Downscoping nicht erzwungen wird.
- In meinem Lauf hatte A den Scope c.read, B hatte c.write als eigenen optionalen Scope, und der Austausch von B lieferte ein Token für A mit c.write. Agent C akzeptierte einen Schreibzugriff, den A nie erlaubt hatte.
- Das ist B, das ein Recht nutzt, das es besitzt, kein Ausbruch. Ohne c.write bei B scheitert derselbe Austausch mit invalid_scope. Es ist eine Konfigurationslektion, keine Schwachstelle.
- Eine Client-Policy mit dem Executor downscope-assertion-grant-enforcer beschränkt den Austausch auf die Scopes von A. Agent C sollte zusätzlich den act-Claim verlangen und den Scope pro Skill prüfen.
- Ich habe nur Keycloak getestet. A2A 1.0.0 überlässt die Autorisierung der Implementierung, und die Agent Card hat kein Feld für Token Exchange.

A2A 1.0.0 ist die aktuelle Version des Agent2Agent-Protokolls. Sie verlangt, dass ein Server jede Anfrage authentifiziert, und überlässt die Autorisierung der Implementierung. Was passiert, wenn Agent B den Agenten C im Auftrag von Agent A aufruft, regelt sie nicht. Dieser Teil ist gewöhnliches OAuth, und das übliche Werkzeug ist der Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)). Ich habe auf einem lokalen Keycloak eine kleine Kette gebaut und eine einzige Frage gestellt: Bleibt das Token, das B für C erhält, innerhalb dessen, was A übergeben hat?

Nein, außer man bittet Keycloak, es zu erzwingen. Um diese Einstellung geht es hier. Wenn Sie mein [erstes Keycloak-Labor zum Token Exchange](https://iamops.dev/de/keycloak-token-exchange-rfc-8693/) gelesen haben: Dieses hier knüpft an die Falle „kein act-Claim“ an und ergänzt die Delegation.

## Was das Labor zeigt

Drei Agenten und ein Autorisierungsserver, alle auf localhost.

- **A** ist der Aufrufer. Es hält ein Token mit dem Scope `agent-b c.read`. Ein `may_act`-Claim in diesem Token nennt B als die Partei, die für A handeln darf.
- **B** ist ein Agent in der Mitte. Er empfängt den Aufruf von A und bittet dann Keycloak um ein Token für den Aufruf von C, mit dem Token von A als `subject_token` und seinem eigenen als `actor_token`.
- **C** ist ein kleiner Notizen-Agent mit einer Lese- und einer Schreib-Skill. Er akzeptiert nur delegierte Tokens und prüft den Scope pro Skill.

| Client | Rolle | Scopes, die er im Austausch anfordern kann |
| --- | --- | --- |
| `agent-a` | Aufrufer, Service Account | `agent-b` standardmäßig, `c.read` auf Anfrage |
| `agent-b` | Agent in der Mitte, führt den Austausch aus | `c.read` und `c.write`, beide optional |
| `agent-c` | Notizen-Agent, nur Audience | keine |

![Sequenzdiagramm: Agent A liest die Agent Card von B, holt ein Token von Keycloak, ruft B auf, und B tauscht es gegen ein delegiertes Token mit act-Claim, bevor es C aufruft.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/00-flow.webp)

*Die Kette. Die Schritte 1 bis 4 sind der Aufruf von B durch A. Die Schritte 5 bis 7 zeigen, wie B das Token von A in ein delegiertes Token verwandelt. Die Schritte 8 bis 10 sind der Aufruf von C.*

Jeder Agent veröffentlicht eine Agent Card unter `/.well-known/agent-card.json` mit einem `oauth2`-Sicherheitsschema und den Scopes pro Skill. Das Schema kann `clientCredentials` sagen und nichts, was dem Token Exchange näherkommt: Ein `OAuthFlows`-Objekt enthält genau einen Flow, und einen Austausch-Flow gibt es nicht. Deshalb steht es bei C im Beschreibungstext der Card, und ein Aufrufer muss ihn lesen.

## Aufbau

Keycloak 26.8.2 aus dem Zip, Java 21, Entwicklungsmodus. Der Standard Token Exchange ist in 26.8 standardmäßig aktiv. Die Delegation, also die Claims `act` und `may_act`, nicht. Sie braucht zwei Preview-Funktionen.

```bash
"$KC_HOME/bin/kc.sh" start-dev --http-port 8080 --features=token-exchange-delegation,parameterized-scopes
```

Keycloak gibt beim Start die aktivierten Preview-Funktionen aus. Ich habe die beiden zusammen aktiviert und nicht einzeln getestet. Ohne sie scheitert meine Kette: Keycloak lehnt in einem einfachen Austausch jedes Subject Token mit `may_act` ab, mit „Subject token with a delegation claim is not allowed for standard token exchange“.

![Terminalausgabe: Keycloak 26.8.2 startet mit den aktivierten Preview-Funktionen parameterized-scopes und token-exchange-delegation, danach meldet das Realm-Skript realm a2a ready.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/01-features.webp)

*Funktionen und Realm. Keycloak 26.8.2 mit zwei aktiven Preview-Funktionen, danach das Realm-Skript.*

Das Realm-Skript legt die drei Clients mit Service Accounts an, die Scopes `agent-b`, `c.read` und `c.write` (jeweils mit Audience-Mapper) und einen fest eingetragenen `may_act`-Mapper bei `agent-a`. Es schaltet außerdem Standard Token Exchange für `agent-b` ein und gibt `agent-b` die Scopes `c.read` und `c.write` als optionale Client Scopes. Merken Sie sich diesen letzten Punkt. Der ganze Beitrag hängt daran.

## Die Aufrufkette funktioniert

A liest die Card von B, fordert bei Keycloak genau die Scopes an, die die Skill nennt, und sendet `message:send`. B tauscht das Token und ruft C auf. Das dekodierte delegierte Token behält A als `sub`, engt `aud` auf C ein, trägt nur `c.read` und ergänzt `act` für B.

![Terminalausgabe: Agent A liest die Agent Card von B, fordert die Scopes agent-b und c.read an und erhält von B eine 200-Antwort, die zwei bei C gespeicherte Notizen zusammenfasst.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/02-chain.webp)

*Der legitime Weg. A bittet B, die Notizen zusammenzufassen. B tauscht das Token von A und liest sie bei C.*

## Der Austausch, den A nie erlaubt hatte

Jetzt fordert B `c.write` an. Das Token von A enthält kein `c.write`. Hier die Anfrage, mit Platzhaltern:

```bash
curl -s "$KC_URL/realms/a2a/protocol/openid-connect/token" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_id=agent-b -d "client_secret=$AGENT_B_SECRET" \
  -d subject_token="$A_TOKEN" -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d actor_token="$B_TOKEN" -d actor_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d audience=agent-c -d scope=c.write
```

Keycloak stellt das Token aus. `sub` ist A, `act` nennt B, `scope` ist `c.write`. C prüft Signatur, Audience, den `act`-Claim und den Scope, den seine Schreib-Skill verlangt, und fügt die Notiz hinzu.

![Terminalausgabe auf Standard-Keycloak: Agent B führt c.write unter seinen optionalen Scopes auf, das Token von A hat den Scope agent-b c.read, das Token, das B für Agent C erhält, hat den Scope c.write mit act agent-b, und C antwortet, dass die Notiz hinzugefügt wurde.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/03-stock.webp)

*Standard-Keycloak. Das Token von A sagt c.read. Das Token für C sagt c.write. C fügt die Notiz hinzu. Ids sind durch Platzhalter ersetzt.*

Ich habe die ganze Abfolge viermal auf einem frischen Keycloak 26.8.2 ausgeführt, zweimal mit den Lab-Skripten und zweimal mit denen aus diesem Beitrag, und jedes Mal dasselbe Ergebnis erhalten.

## Die Kontrolle: B besitzt c.write

Bevor ich das Eskalation nenne, habe ich geprüft, wessen Recht hier genutzt wird. In meinem Realm hat B `c.write` als eigenen optionalen Scope. Ich habe ihn dort eingetragen. B hat also nichts erhalten, was es nie hätte haben dürfen. Ich habe `c.write` aus den optionalen Scopes von B entfernt und denselben Austausch wiederholt.

![Terminalausgabe des Kontrolllaufs: Nachdem c.write aus den optionalen Client Scopes von Agent B gelöscht wurde, wird derselbe Austausch mit invalid_scope abgelehnt, Invalid scopes: c.write.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/04-control.webp)

*Die Kontrolle. Ohne c.write bei B wird nichts ausgestellt. B bleibt innerhalb seiner eigenen Rechte.*

Damit ist eines geklärt. B kann nicht über das hinausgehen, was es selbst besitzt, und es liegt kein Bug im Sinne einer Umgehung vor. Verloren geht etwas anderes: Der Scope des neuen Tokens wird durch den Scope-Vorrat von B begrenzt und nicht durch das Token von A. A hatte „lesen“ gesagt, und einen Schritt weiter bedeutete das nichts mehr. RFC 8693 überlässt das dem Server: `scope` ist „the desired scope of the requested security token“, und seine Werte sind „service specific“ ([Abschnitt 2.1](https://www.rfc-editor.org/rfc/rfc8693#section-2.1)). Nichts verlangt, dass das Ergebnis eine Teilmenge des Subject Tokens ist.

Für Agenten ist das wichtig, weil C `sub` A und `act` B protokolliert. Wer das Log liest, sieht „A hat eine Notiz geschrieben“. A hat dem nie zugestimmt.

## Den Austausch mit der Downscope-Policy begrenzen

Keycloak hat dafür einen Executor für Client-Policies: `downscope-assertion-grant-enforcer`. Er begrenzt die Scopes des neuen Tokens auf die, die schon im Subject Token stehen, und antwortet sonst mit `invalid_scope`. Er braucht keine Konfiguration. Ich habe ihn mit einer einzigen Policy auf alle Clients des Realms angewendet.

```json
{"profiles":[{"name":"downscope-only","description":"exchange can narrow, never widen",
  "executors":[{"executor":"downscope-assertion-grant-enforcer","configuration":{}}]}]}
```

Mit `c.write` wieder bei B und aktiver Policy wird der Austausch abgelehnt. Der legitime Austausch mit `c.read` funktioniert weiterhin.

![Terminalausgabe bei aktiver Downscope-Policy: Der Austausch mit c.write wird abgelehnt, weil c.write nicht im ursprünglichen Access Token steht, und der Austausch mit c.read liefert weiterhin ein delegiertes Token, das C akzeptiert.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/05-enforcer.webp)

*Mit der Policy. c.write wird abgelehnt, weil das Token von A es nicht trägt. c.read funktioniert weiterhin. C listet auch die Notiz aus dem Standardlauf auf.*

Die letzte Zeile dieser Ausgabe ist die Notiz aus dem Standardlauf. Sie bleibt, bis Sie C neu starten.

## Was C zusätzlich prüfen sollte

Die Policy lebt auf dem Autorisierungsserver. C sollte sich nicht allein darauf verlassen.

- Verlangen Sie den `act`-Claim und prüfen Sie `act.client_id` gegen die Agenten, die Sie erwarten. Mein C antwortet ohne ihn mit 403.
- Prüfen Sie den Scope pro Skill. Mein C braucht `c.read` zum Lesen und `c.write` zum Schreiben.
- Prüfen Sie `aud`. Ein Token für B wird von C mit 401 abgelehnt.
- Behandeln Sie `may_act` nicht als Beweis. Als B das Token von C als Actor vorlegte, lehnte Keycloak mit einer Audience-Meldung ab. Ob es den Actor mit `may_act` vergleicht, habe ich nicht untersucht.

## Stolperfallen

- **Der Enforcer und ein Audience-Mapper auf Client-Ebene.** In meinem ersten Aufbau lag die Audience von C in einem Mapper am Client B. Mit aktivem Enforcer scheiterte dann jeder Austausch mit „Requested audience not available: agent-c“. Der Umzug des Mappers auf die Scopes `c.read` und `c.write` löste es. Warum, weiß ich nicht. Testen Sie es in Ihrem eigenen Realm.
- **Audience über Scopes hat einen Nebeneffekt.** `c.read` trägt die Audience von C, daher hat das Token von A `aud` B und C. Was A daran hindert, es bei C zu nutzen, ist die `act`-Pflicht, nicht die Audience.
- **Die Fehlermeldung beim falschen Actor ist vage.** Der Client sieht `access_denied` und „Client is not within the token audience“. Das Keycloak-Ereignisprotokoll nennt den Actor.
- **`may_act` ist in meinem Realm fest eingetragen.** In einem echten System sollte es aus einer Policy stammen und mit dem Token leben.

## Was ich nicht ausgeführt habe

Ich habe nur Keycloak 26.8.2 ausgeführt. Entra On-Behalf-Of, Okta und Auth0 habe ich nicht getestet und mache daher keine Aussage dazu, wie sie den Scope im Austausch begrenzen. Nur eine Delegationsstufe: keine verschachtelte `act`-Kette. Keine Tasks, kein Streaming, keine signierten Agent Cards, kein TLS und keine senderbeschränkten Tokens. Kein Nutzer in der Kette: Das Subject ist der Service Account von Agent A. Die Agenten sind meine eigenen Flask-Programme, und ihre Client Secrets sind statische Lab-Werte.

*Die Terminalbilder wurden aus der gespeicherten Ausgabe der Läufe neu gezeichnet, mit durch Platzhalter ersetzten Ids. Nichts davon sind echte Zugangsdaten.*

Zu den Standards dahinter siehe [ID-JAG erklärt](https://iamops.dev/de/id-jag-explained/) und [warum ein MCP-Server Tokens nicht durchreichen darf](https://iamops.dev/de/mcp-server-no-token-passthrough/).

## Dieses Lab nachbauen

Etwa 40 Minuten auf einem Laptop: ein lokales Keycloak mit zwei Preview-Funktionen, ein Skript für den Realm, drei kleine Agenten in Python und drei Austauschvorgänge: Standard, Kontrolle und mit der Downscope-Policy. Ö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_HOME='<KEYCLOAK_DIR>'          # the unpacked keycloak-26.8.2 folder
export JAVA_HOME='<JDK_DIR>'             # a JDK 21
export KC_URL="http://localhost:8080"
export KC_ADMIN_USER="admin"
export KC_ADMIN_PASSWORD='<ADMIN_PASSWORD>'
export AGENT_A_SECRET='<AGENT_A_SECRET>'
export AGENT_B_SECRET='<AGENT_B_SECRET>'
export AGENT_C_SECRET='<AGENT_C_SECRET>'
```

### Schritt 1: Keycloak mit den Delegationsfunktionen starten

**Ziel.** Starten Sie einen lokalen Autorisierungsserver mit token-exchange-delegation und parameterized-scopes, den beiden Preview-Funktionen, die den act-Claim hinzufügen.

**Voraussetzungen**

- Keycloak 26.8.2 entpackt und ein JDK 21; curl und Python 3.10 oder neuer
- Port 8080 frei; lassen Sie dieses Terminal offen und nutzen Sie für die nächsten Schritte ein zweites

`start-keycloak.sh` (bash)

```bash
export KC_BOOTSTRAP_ADMIN_USERNAME="$KC_ADMIN_USER" KC_BOOTSTRAP_ADMIN_PASSWORD="$KC_ADMIN_PASSWORD"
"$KC_HOME/bin/kc.sh" start-dev --http-port 8080 --features=token-exchange-delegation,parameterized-scopes
```

**Erwartete Ausgabe**

```text
INFO  [org.keycloak.common.Profile] (main) Preview features enabled: parameterized-scopes:v1, token-exchange-delegation:v1
WARN  [org.keycloak.common.Profile] (main) Deprecated features identity-brokering-api:v1, twitter-broker:v1 enabled by default. Check the upgrading guide for steps to use later versions if available.
INFO  [io.quarkus] (main) Keycloak 26.8.2 on JVM (powered by Quarkus 3.40.1.1) started in 16.223s. Listening on: http://localhost:8080
```

### Schritt 2: Realm, Clients und may_act-Claim anlegen

**Ziel.** Legen Sie den Realm a2a an: drei Clients mit Service Accounts, drei Scopes mit Audience und einen Mapper, der may_act in das Token von A schreibt. B erhält c.read und c.write als optionale Scopes.

**Voraussetzungen**

- Der env-Block in diesem Terminal gesetzt; Keycloak aus dem vorigen Schritt läuft noch
- Das Skript braucht etwa eine Minute, weil es die Standard-Scopes jedes Clients kürzt

`kc-realm.sh` (bash)

```bash
#!/usr/bin/env bash
# Realm "a2a": three agents as clients with service accounts, scopes with audiences, and a may_act claim that names the actor.
set -euo pipefail
: "${KC_HOME:?}" "${JAVA_HOME:?}" "${KC_ADMIN_PASSWORD?}" "${AGENT_A_SECRET:?}" "${AGENT_B_SECRET:?}" "${AGENT_C_SECRET:?}"
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "${KC_URL:-http://localhost:8080}" --realm master --user "${KC_ADMIN_USER:-admin}" --password "$KC_ADMIN_PASSWORD" >/dev/null
$KCADM create realms -s realm=a2a -s enabled=true -s sslRequired=none >/dev/null
scope() { # name audience
  $KCADM create client-scopes -r a2a -s name="$1" -s protocol=openid-connect -s 'attributes."include.in.token.scope"=true' >/dev/null
  local id; id=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, -v n="$1" '$2==n{print $1}')
  $KCADM create client-scopes/$id/protocol-mappers/models -r a2a -s name="aud-$2" -s protocol=openid-connect -s protocolMapper=oidc-audience-mapper \
    -s "config.\"included.client.audience\"=$2" -s 'config."access.token.claim"=true' -s 'config."id.token.claim"=false' >/dev/null
  echo "$id"
}
S_B=$(scope agent-b agent-b); S_CR=$(scope c.read agent-c); S_CW=$(scope c.write agent-c)
agent() { # client id, secret
  $KCADM create clients -r a2a -s clientId="$1" -s secret="$2" -s publicClient=false -s serviceAccountsEnabled=true \
    -s standardFlowEnabled=false -s directAccessGrantsEnabled=false >/dev/null
  $KCADM get clients -r a2a -q clientId="$1" --fields id --format csv --noquotes
}
A=$(agent agent-a "$AGENT_A_SECRET"); B=$(agent agent-b "$AGENT_B_SECRET"); C=$(agent agent-c "$AGENT_C_SECRET")
# keep the tokens small: drop the default profile, email and roles scopes from every agent
for CID in $A $B $C; do
  for SN in roles profile email web-origins acr basic; do
    SID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, -v n="$SN" '$2==n{print $1}')
    [ -n "$SID" ] && $KCADM delete clients/$CID/default-client-scopes/$SID -r a2a >/dev/null 2>&1 || true
  done
done
# agent-b performs the exchange
$KCADM update clients/$B -r a2a -s 'attributes."standard.token.exchange.enabled"=true' >/dev/null
SA_B=$($KCADM get clients/$B/service-account-user -r a2a --fields id --format csv --noquotes)
# agent-a: may call agent-b by default, may add c.read when it asks for it
$KCADM update clients/$A/default-client-scopes/$S_B -r a2a >/dev/null
$KCADM update clients/$A/optional-client-scopes/$S_CR -r a2a >/dev/null
# the claim value is JSON, so pass the mapper as a file; kcadm -s cannot carry nested quotes
MAP=$(mktemp)
cat > "$MAP" <<JSON
{"name":"may-act-agent-b","protocol":"openid-connect","protocolMapper":"oidc-hardcoded-claim-mapper",
 "config":{"claim.name":"may_act","claim.value":"{\"sub\":\"$SA_B\",\"client_id\":\"agent-b\"}","jsonType.label":"JSON",
           "access.token.claim":"true","id.token.claim":"false"}}
JSON
$KCADM create clients/$A/protocol-mappers/models -r a2a -f "$MAP" >/dev/null; rm -f "$MAP"
# agent-b: its own token is the actor token; c.read and c.write are optional scopes it can ask for in an exchange
$KCADM update clients/$B/optional-client-scopes/$S_CR -r a2a >/dev/null
$KCADM update clients/$B/optional-client-scopes/$S_CW -r a2a >/dev/null
echo "realm a2a ready"
```

`create-realm.sh` (bash)

```bash
chmod +x kc-realm.sh
./kc-realm.sh 2>&1 | grep -v "^Created\|^Logging"
```

**Erwartete Ausgabe**

```text
realm a2a ready
```

### Schritt 3: Agent B und Agent C speichern und starten

**Ziel.** Vier kleine Python-Dateien: eine gemeinsame Bibliothek, Agent C (Notizen, akzeptiert nur delegierte Tokens), Agent B (führt den Austausch aus) und Agent A (der Aufrufer). Starten Sie B und C und lesen Sie die Agent Card von C.

**Voraussetzungen**

- Python 3.10 oder neuer; Ports 19402 und 19403 frei
- Speichern Sie die vier Dateien in einem Ordner, demselben wie kc-realm.sh

`a2alib.py` (python)

```python
import json, os, urllib.error, urllib.parse, urllib.request, uuid
import jwt
from flask import Flask, Response, request

KC_URL = os.environ.get("KC_URL", "http://localhost:8080")
ISS = f"{KC_URL}/realms/a2a"
TOKEN_URL = f"{ISS}/protocol/openid-connect/token"
JWKS = jwt.PyJWKClient(f"{ISS}/protocol/openid-connect/certs")
MEDIA = "application/a2a+json"
AT = "urn:ietf:params:oauth:token-type:access_token"


class Reject(Exception):
    def __init__(self, http, status, reason, message):
        self.http, self.status, self.reason, self.message = http, status, reason, message


def error_body(r):
    return {"error": {"code": r.http, "status": r.status, "message": r.message,
                      "details": [{"@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": r.reason, "domain": "a2a-protocol.org"}]}}


def verify(auth_header, my_audience):
    if not auth_header or not auth_header.lower().startswith("bearer "):
        raise Reject(401, "UNAUTHENTICATED", "MISSING_TOKEN", "bearer token required")
    token = auth_header[7:].strip()
    try:
        key = JWKS.get_signing_key_from_jwt(token).key
        return jwt.decode(token, key, algorithms=["RS256"], audience=my_audience, issuer=ISS,
                          options={"require": ["exp", "iss", "aud", "sub"]})
    except jwt.InvalidAudienceError:
        raise Reject(401, "UNAUTHENTICATED", "WRONG_AUDIENCE", f"token is not meant for {my_audience}")
    except jwt.PyJWTError as e:
        raise Reject(401, "UNAUTHENTICATED", "INVALID_TOKEN", f"token rejected: {type(e).__name__}")


def scopes(claims):
    return set((claims.get("scope") or "").split())


def secret_of(client_id):
    return os.environ[client_id.upper().replace("-", "_") + "_SECRET"]


def post_form(data):
    req = urllib.request.Request(TOKEN_URL, data=urllib.parse.urlencode(data).encode())
    try:
        with urllib.request.urlopen(req) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        return {"http_status": e.code, **json.load(e)}


def client_credentials(client_id, scope=None):
    d = {"grant_type": "client_credentials", "client_id": client_id, "client_secret": secret_of(client_id)}
    if scope:
        d["scope"] = scope
    return post_form(d)


def exchange(client_id, subject_token, actor_token, audience, scope):
    d = {"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "client_id": client_id,
         "client_secret": secret_of(client_id), "subject_token": subject_token, "subject_token_type": AT,
         "audience": audience, "scope": scope}
    if actor_token:
        d.update(actor_token=actor_token, actor_token_type=AT)
    return post_form(d)


def fetch_card(base):
    with urllib.request.urlopen(f"{base}/.well-known/agent-card.json") as r:
        return json.load(r)


def send_message(base, token, text):
    body = {"message": {"messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"text": text}]}}
    h = {"Content-Type": MEDIA, "A2A-Version": "1.0"}
    if token:
        h["Authorization"] = f"Bearer {token}"
    req = urllib.request.Request(f"{base}/message:send", data=json.dumps(body).encode(), headers=h, method="POST")
    try:
        with urllib.request.urlopen(req) as r:
            return r.status, json.load(r)
    except urllib.error.HTTPError as e:
        return e.code, json.load(e)


def reply(text):
    return {"message": {"messageId": str(uuid.uuid4()), "role": "ROLE_AGENT", "parts": [{"text": text}]}}


def claims_unverified(token):
    import base64
    p = token.split(".")[1]
    return json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4)))


def serve(name, port, card, handle):
    app = Flask(name)
    out = lambda obj, status=200: Response(json.dumps(obj), status=status, mimetype=MEDIA)
    app.get("/.well-known/agent-card.json")(lambda: out(card))

    @app.post("/message:send")
    def send():
        try:
            return out(reply(handle(request)))
        except Reject as r:
            print(f"AUDIT {name}: DENIED {r.http} {r.reason}", flush=True)
            return out(error_body(r), r.http)
    app.run(port=port)
```

`agent_c.py` (python)

```python
import os
from a2alib import *

PORT = int(os.environ.get("C_PORT", "19403"))
NOTES = ["note 1: quarterly review is on Thursday", "note 2: renew the staging certificate"]
need = lambda s: [{"schemes": {"keycloak": {"list": [s]}}}]
CARD = {
    "name": "agent-c notes", "description": "Keeps a short list of notes. Reads and writes need a delegated token.", "version": "1.0.0",
    "supportedInterfaces": [{"url": f"http://localhost:{PORT}", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}],
    "capabilities": {"streaming": False, "pushNotifications": False},
    "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"],
    "securitySchemes": {"keycloak": {"oauth2SecurityScheme": {
        "description": "Tokens come from Keycloak via RFC 8693 token exchange, with an actor token. The scheme types below cannot say that, so this text does.",
        "oauth2MetadataUrl": f"{ISS}/.well-known/oauth-authorization-server",
        "flows": {"clientCredentials": {"tokenUrl": TOKEN_URL, "scopes": {"c.read": "read notes", "c.write": "add notes"}}}}}},

    "skills": [
        {"id": "read-notes", "name": "Read notes", "description": "Say 'read' to get all notes.", "tags": ["notes"], "securityRequirements": need("c.read")},
        {"id": "add-note", "name": "Add a note", "description": "Say 'write: <text>' to add one.", "tags": ["notes"], "securityRequirements": need("c.write")}],
}

def handle(req):
    c = verify(req.headers.get("Authorization"), "agent-c")
    act = c.get("act") or {}
    if act.get("client_id") != "agent-b":
        raise Reject(403, "PERMISSION_DENIED", "ACTOR_REQUIRED", "a delegated token from agent-b is required")
    text = req.get_json(force=True)["message"]["parts"][0]["text"].strip()
    skill = "c.write" if text.startswith("write:") else "c.read"
    if skill not in scopes(c):
        raise Reject(403, "PERMISSION_DENIED", "INSUFFICIENT_SCOPE", f"skill needs scope {skill}")
    print(f"AUDIT c: sub={c['sub'][:8]} actor={act['client_id']} scope='{c.get('scope')}' skill={skill}", flush=True)
    if skill == "c.write":
        NOTES.append(text[6:].strip())
        return f"added, {len(NOTES)} notes now"
    return "\n".join(NOTES)

serve("c", PORT, CARD, handle)
```

`agent_b.py` (python)

```python
import os
from a2alib import *

PORT, C_BASE = int(os.environ.get("B_PORT", "19402")), os.environ.get("C_BASE", "http://localhost:19403")
need = lambda *s: [{"schemes": {"keycloak": {"list": list(s)}}}]
CARD = {
    "name": "agent-b summariser", "description": "Reads the notes through agent C and sums them up.", "version": "1.0.0",
    "supportedInterfaces": [{"url": f"http://localhost:{PORT}", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}],
    "capabilities": {"streaming": False, "pushNotifications": False},
    "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"],
    "securitySchemes": {"keycloak": {"oauth2SecurityScheme": {
        "oauth2MetadataUrl": f"{ISS}/.well-known/oauth-authorization-server",
        "flows": {"clientCredentials": {"tokenUrl": TOKEN_URL, "scopes": {"agent-b": "call agent B", "c.read": "allow B to read notes for you"}}}}}},

    "skills": [{"id": "summarize", "name": "Summarise notes", "description": "Say 'summarize'.", "tags": ["notes"], "securityRequirements": need("agent-b", "c.read")}],
}

def handle(req):
    bearer = req.headers.get("Authorization")
    c = verify(bearer, "agent-b")
    for s in ("agent-b", "c.read"):
        if s not in scopes(c):
            raise Reject(403, "PERMISSION_DENIED", "INSUFFICIENT_SCOPE", f"skill needs scope {s}")
    actor = client_credentials("agent-b")["access_token"]
    ex = exchange("agent-b", bearer[7:].strip(), actor, audience="agent-c", scope="c.read")
    if "access_token" not in ex:
        raise Reject(502, "UNAVAILABLE", "EXCHANGE_FAILED", f"token exchange refused: {ex.get('error_description')}")
    print(f"AUDIT b: exchanged for sub={c['sub'][:8]} scope='{ex['scope']}'", flush=True)
    code, body = send_message(C_BASE, ex["access_token"], "read")
    if code != 200:
        raise Reject(502, "UNAVAILABLE", "DOWNSTREAM_REFUSED", f"agent C said {code}")
    notes = body["message"]["parts"][0]["text"].splitlines()
    return f"{len(notes)} notes. First: {notes[0]}"

serve("b", PORT, CARD, handle)
```

`agent_a.py` (python)

```python
import json, sys
from a2alib import *

B = "http://localhost:19402"
card = fetch_card(B)
skill = card["skills"][0]
want = skill["securityRequirements"][0]["schemes"]["keycloak"]["list"]
flow = card["securitySchemes"]["keycloak"]["oauth2SecurityScheme"]["flows"]["clientCredentials"]
print(f"card says: skill '{skill['id']}' needs scopes {want}, token endpoint {flow['tokenUrl'].split('/realms/')[1]}")
tok = client_credentials("agent-a", " ".join(want))
claims = claims_unverified(tok["access_token"])
print(f"token: aud={claims['aud']} scope='{claims['scope']}' may_act={claims['may_act']['client_id']}")
code, body = send_message(B, tok["access_token"], sys.argv[1] if len(sys.argv) > 1 else "summarize")
print(code, body["message"]["parts"][0]["text"] if code == 200 else json.dumps(body))
```

`start-agents.sh` (bash)

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -q "PyJWT==2.15.1" "Flask==3.1.3" "cryptography==50.0.2"
nohup python3 agent_c.py > c.log 2>&1 &
nohup python3 agent_b.py > b.log 2>&1 &
sleep 3
curl -s localhost:19403/.well-known/agent-card.json | python3 -c "import sys,json;c=json.load(sys.stdin);print(c['name']);print(list(c['securitySchemes']));print(c['skills'][0]['securityRequirements'])"
```

**Erwartete Ausgabe**

```text
agent-c notes
['keycloak']
[{'schemes': {'keycloak': {'list': ['c.read']}}}]
```

### Schritt 4: Die Kette als Agent A aufrufen

**Ziel.** A liest die Card von B, fragt bei Keycloak die in der Skill genannten Scopes an und sendet eine Nachricht. B tauscht das Token von A gegen ein Token für C und liest die Notizen.

**Voraussetzungen**

- Schritte 1 bis 3 erledigt, in derselben virtuellen Umgebung

`call-chain.sh` (bash)

```bash
python3 agent_a.py
```

**Erwartete Ausgabe**

```text
card says: skill 'summarize' needs scopes ['agent-b', 'c.read'], token endpoint a2a/protocol/openid-connect/token
token: aud=['agent-c', 'agent-b'] scope='agent-b c.read' may_act=agent-b
200 2 notes. First: note 1: quarterly review is on Thursday
```

### Schritt 5: c.write auf Standard-Keycloak anfordern

**Ziel.** B tauscht das Token von A und fordert c.write an. Das Token von A hat nur c.read. Lesen Sie zuerst die optionalen Scopes von B, dann sehen Sie, was Keycloak ausstellt und was C damit tut.

**Voraussetzungen**

- Schritte 1 bis 4 erledigt; das ist die Standardkonfiguration, noch ohne Policy
- Speichern Sie escal.py aus dem Block unten neben den anderen Dateien

`escal.py` (python)

```python
import json, sys
from a2alib import *

scope = sys.argv[1]
KEYS = ("aud", "scope", "azp", "sub", "may_act", "act")
show = lambda t: json.dumps({k: claims_unverified(t)[k] for k in KEYS if k in claims_unverified(t)}, indent=1)
a = client_credentials("agent-a", "agent-b c.read")["access_token"]
b = client_credentials("agent-b")["access_token"]
print("## A's token\n" + show(a))
ex = exchange("agent-b", a, b, "agent-c", scope)
if "access_token" not in ex:
    sys.exit(f"exchange refused: {ex['error']} - {ex['error_description']}")
print("## token B got for C\n" + show(ex["access_token"]))
text = "write: evidence note" if scope == "c.write" else "read"
code, body = send_message("http://localhost:19403", ex["access_token"], text)
print("C says:", body["message"]["parts"][0]["text"] if code == 200 else f"{code} {body['error']['details'][0]['reason']}")
```

`stock-exchange.sh` (bash)

```bash
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
B_ID=$($KCADM get clients -r a2a -q clientId=agent-b --fields id --format csv --noquotes)
CW_ID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, '$2=="c.write"{print $1}')
$KCADM get clients/$B_ID/optional-client-scopes -r a2a --fields name --format csv --noquotes | tr '\n' ' '; echo
python3 escal.py c.write
```

**Erwartete Ausgabe**

```text
address delegation:user phone offline_access organization delegation:client microprofile-jwt c.read c.write 
## A's token
{
 "aud": [
  "agent-c",
  "agent-b"
 ],
 "scope": "agent-b c.read",
 "azp": "agent-a",
 "sub": "<A-ID>",
 "may_act": {
  "sub": "<B-ID>",
  "client_id": "agent-b"
 }
}
## token B got for C
{
 "aud": "agent-c",
 "scope": "c.write",
 "azp": "agent-b",
 "sub": "<A-ID>",
 "act": {
  "sub": "<B-ID>",
  "client_id": "agent-b"
 }
}
C says: added, 3 notes now
```

### Schritt 6: Kontrolle: B das c.write entziehen

**Ziel.** Entfernen Sie c.write aus den optionalen Scopes von B und wiederholen Sie denselben Austausch. Scheitert er, nutzte B ein Recht, das es besitzt. Setzen Sie den Scope danach wieder ein.

**Voraussetzungen**

- Schritt 5 erledigt
- Die Befehle melden sich neu an, jedes Terminal mit dem env-Block genügt

`control.sh` (bash)

```bash
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
B_ID=$($KCADM get clients -r a2a -q clientId=agent-b --fields id --format csv --noquotes)
CW_ID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, '$2=="c.write"{print $1}')
$KCADM delete clients/$B_ID/optional-client-scopes/$CW_ID -r a2a
python3 escal.py c.write
$KCADM update clients/$B_ID/optional-client-scopes/$CW_ID -r a2a
```

**Erwartete Ausgabe**

```text
exchange refused: invalid_scope - Invalid scopes: c.write
```

### Schritt 7: Die Downscope-Policy einschalten

**Ziel.** Fügen Sie eine Client-Policy mit dem Executor downscope-assertion-grant-enforcer hinzu und wiederholen Sie dann den Austausch mit c.write und den legitimen mit c.read.

**Voraussetzungen**

- Schritt 6 erledigt, mit c.write wieder bei B

`kc-downscope.sh` (bash)

```bash
#!/usr/bin/env bash
# Client policy: every token exchange in realm a2a may only carry scopes that were already in the subject token.
set -euo pipefail
: "${KC_HOME:?}" "${JAVA_HOME:?}" "${KC_ADMIN_PASSWORD?}"
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "${KC_URL:-http://localhost:8080}" --realm master --user "${KC_ADMIN_USER:-admin}" --password "$KC_ADMIN_PASSWORD" >/dev/null
TMP=$(mktemp)
cat > "$TMP" <<'JSON'
{"profiles":[{"name":"downscope-only","description":"exchange can narrow, never widen",
  "executors":[{"executor":"downscope-assertion-grant-enforcer","configuration":{}}]}]}
JSON
$KCADM update client-policies/profiles -r a2a -f "$TMP"
cat > "$TMP" <<'JSON'
{"policies":[{"name":"all-clients-downscope","description":"applies to every client in the realm","enabled":true,
  "conditions":[{"condition":"any-client","configuration":{}}],"profiles":["downscope-only"]}]}
JSON
$KCADM update client-policies/policies -r a2a -f "$TMP"; rm -f "$TMP"
echo "downscope policy active"
```

`downscope.sh` (bash)

```bash
chmod +x kc-downscope.sh
./kc-downscope.sh
python3 escal.py c.write
python3 escal.py c.read
```

**Erwartete Ausgabe**

```text
downscope policy active
## A's token
{
 "aud": [
  "agent-c",
  "agent-b"
 ],
 "scope": "agent-b c.read",
 "azp": "agent-a",
 "sub": "<A-ID>",
 "may_act": {
  "sub": "<B-ID>",
  "client_id": "agent-b"
 }
}
exchange refused: invalid_scope - Scopes [c.write] not present in the initial access token [agent-b, c.read]
## A's token
{
 "aud": [
  "agent-c",
  "agent-b"
 ],
 "scope": "agent-b c.read",
 "azp": "agent-a",
 "sub": "<A-ID>",
 "may_act": {
  "sub": "<B-ID>",
  "client_id": "agent-b"
 }
}
## token B got for C
{
 "aud": "agent-c",
 "scope": "c.read",
 "azp": "agent-b",
 "sub": "<A-ID>",
 "act": {
  "sub": "<B-ID>",
  "client_id": "agent-b"
 }
}
C says: note 1: quarterly review is on Thursday
note 2: renew the staging certificate
evidence note
```

### Schritt 8: Aufräumen

**Ziel.** Beenden Sie die Agenten und Keycloak, löschen Sie den Keycloak-Datenordner und die Logs und entfernen Sie die Lab-Secrets aus der Umgebung.

**Voraussetzungen**

- Drücken Sie zuerst Strg+C in dem Terminal, in dem Keycloak läuft
- Der Keycloak-Ordner ist der, den Sie nur für dieses Lab entpackt haben

`cleanup.sh` (bash)

```bash
pkill -f "agent_[abc].py"
rm -rf "$KC_HOME/data" c.log b.log __pycache__ .venv
unset AGENT_A_SECRET AGENT_B_SECRET AGENT_C_SECRET KC_ADMIN_PASSWORD
pgrep -f "agent_[abc].py" > /dev/null || echo "agents stopped"
```

**Erwartete Ausgabe**

```text
agents stopped
```


## Sources

- [A2A Protocol specification 1.0.0](https://a2a-protocol.org/latest/specification/)
- [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)
- [RFC 6749: The OAuth 2.0 Authorization Framework, client credentials grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)
