iamops.dev
Argo auf X RSS-Feed
DEDeutsch

Labs Technisch 8 Min. Lesezeit

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.

Zwei Aufnahmen aus meinem A2A-Labor auf Keycloak: der Standardaustausch, bei dem Agent B für Agent C ein Token mit dem Scope c.write erhält, obwohl A nur c.read hatte, und derselbe Austausch, der bei aktiver Downscope-Policy mit invalid_scope abgelehnt wird.
Kurz gesagtWenn Agent B für Agent A den Agenten C aufruft, tauscht B das Token von…
  • 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.
Dieses Lab nachbauen 8 Schritte

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.

Zu den Schritten

So funktioniert es

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: Downscoping beim Token Exchange für Agent-zu-Agent-Aufrufe erzwingen
Read the whole lab here (Markdown): https://iamops.dev/de/enforce-downscoping-token-exchange-a2a.md

What the lab needs before the first step:
- Keycloak 26.8.2 unpacked and a JDK 21; curl and Python 3.10 or newer
- 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): <KEYCLOAK_DIR>, <JDK_DIR>, <ADMIN_PASSWORD>, <AGENT_A_SECRET>, <AGENT_B_SECRET>, <AGENT_C_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.

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). 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 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.
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.
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.
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.
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.
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). 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.
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 und warum ein MCP-Server Tokens nicht durchreichen darf.

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

bash · env.sh
# 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 1Keycloak 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
bash · start-keycloak.sh
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

Ausgabe
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 2Realm, 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
bash · kc-realm.sh
#!/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"
bash · create-realm.sh
chmod +x kc-realm.sh
./kc-realm.sh 2>&1 | grep -v "^Created\|^Logging"

Erwartete Ausgabe

Ausgabe
realm a2a ready
Schritt 3Agent 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
python · a2alib.py
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)
python · agent_c.py
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)
python · agent_b.py
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)
python · agent_a.py
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))
bash · start-agents.sh
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

Ausgabe
agent-c notes
['keycloak']
[{'schemes': {'keycloak': {'list': ['c.read']}}}]
Schritt 4Die 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
bash · call-chain.sh
python3 agent_a.py

Erwartete Ausgabe

Ausgabe
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 5c.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
python · escal.py
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']}")
bash · stock-exchange.sh
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

Ausgabe
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 6Kontrolle: 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
bash · control.sh
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

Ausgabe
exchange refused: invalid_scope - Invalid scopes: c.write
Schritt 7Die 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
bash · kc-downscope.sh
#!/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"
bash · downscope.sh
chmod +x kc-downscope.sh
./kc-downscope.sh
python3 escal.py c.write
python3 escal.py c.read

Erwartete Ausgabe

Ausgabe
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 8Aufrä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
bash · cleanup.sh
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

Ausgabe
agents stopped

Quellen#

Diesen Beitrag diskutieren#

Hat es dir geholfen? Teile es und sag mir, was du denkst.

Auf X folgen

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

Verwandte Beiträge und Labs