En bref
- Quand l'agent B appelle l'agent C pour le compte de l'agent A, B échange le jeton de A contre un nouveau. Sur Keycloak 26.8.2, le scope de ce nouveau jeton suit les scopes de B, pas le jeton remis par A, tant qu'on n'impose pas le downscoping.
- Dans mon essai, A avait c.read, B avait c.write comme scope optionnel à lui, et l'échange de B a renvoyé un jeton pour A avec c.write. L'agent C a accepté une écriture que A n'avait jamais accordée.
- C'est B qui utilise un droit qu'il possède, pas B qui sort de son cadre. Sans c.write chez B, le même échange échoue avec invalid_scope. C'est une leçon de configuration, pas une vulnérabilité.
- Une client policy avec l'executor downscope-assertion-grant-enforcer limite l'échange aux scopes de A. L'agent C devrait aussi exiger le claim act et vérifier le scope pour chaque skill.
- Je n'ai testé que Keycloak. A2A 1.0.0 laisse l'autorisation à l'implémentation, et l'Agent Card n'a aucun champ pour le token exchange.
Refaire ce lab
J’ai écrit ce lab pour que vous puissiez le refaire vous-même. Chaque étape contient les commandes à copier et la sortie que j’ai obtenue, et vous pouvez la cocher une fois faite. Les coches restent uniquement dans ce navigateur.
Copie un prompt prêt à l’emploi pour Claude Code, Cursor, Codex ou tout autre agent de code. Pour les environnements de test uniquement.
Afficher le prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Imposer le downscoping dans le token exchange pour les appels entre agents Read the whole lab here (Markdown): https://iamops.dev/fr/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 est la version actuelle du protocole Agent2Agent. Elle exige qu’un serveur authentifie chaque requête et laisse l’autorisation à l’implémentation. Elle ne dit pas ce qui se passe quand l’agent B appelle l’agent C pour le compte de l’agent A. Cette partie, c’est de l’OAuth ordinaire, et l’outil habituel est le token exchange (RFC 8693). J’ai monté une petite chaîne sur un Keycloak local et posé une seule question : le jeton que B obtient pour C reste-t-il dans ce que A a remis ?
Non, sauf si on demande à Keycloak de l’imposer. Cet article porte sur ce réglage. Si vous avez lu mon premier lab sur le token exchange avec Keycloak, celui-ci reprend au piège « pas de claim act » et ajoute la délégation.
Ce que montre ce lab#
Trois agents et un serveur d’autorisation, tous sur localhost.
- A est l’appelant. Il détient un jeton avec le scope
agent-b c.read. Un claimmay_actdans ce jeton désigne B comme la partie autorisée à agir pour lui. - B est un agent intermédiaire. Il reçoit l’appel de A, puis demande à Keycloak un jeton pour appeler C, avec le jeton de A comme
subject_tokenet le sien commeactor_token. - C est un petit agent de notes avec une skill de lecture et une d’écriture. Il n’accepte que des jetons délégués et vérifie le scope pour chaque skill.
| Client | Rôle | Scopes qu’il peut demander dans un échange |
|---|---|---|
agent-a |
Appelant, service account | agent-b par défaut, c.read sur demande |
agent-b |
Agent intermédiaire, effectue l’échange | c.read et c.write, tous deux optionnels |
agent-c |
Agent de notes, audience seulement | aucun |

Chaque agent publie une Agent Card à /.well-known/agent-card.json avec un schéma de sécurité oauth2 et les scopes par skill. Le schéma peut dire clientCredentials et rien qui se rapproche du token exchange : un objet OAuthFlows contient exactement un flux, et il n’existe pas de flux d’échange. C’est pourquoi la card de C le dit dans le texte de sa description, et un appelant doit le lire.
Mise en place#
Keycloak 26.8.2 depuis le zip, Java 21, mode développement. Le standard token exchange est actif par défaut dans la 26.8. La délégation, c’est-à-dire les claims act et may_act, ne l’est pas. Elle demande deux fonctions en préversion.
"$KC_HOME/bin/kc.sh" start-dev --http-port 8080 --features=token-exchange-delegation,parameterized-scopesKeycloak affiche au démarrage les fonctions en préversion activées. Je les ai activées ensemble et je ne les ai pas testées une par une. Sans elles, ma chaîne échoue : Keycloak refuse dans un échange simple tout subject token qui porte may_act, avec « Subject token with a delegation claim is not allowed for standard token exchange ».

Le script du realm crée les trois clients avec service accounts, les scopes agent-b, c.read et c.write (chacun avec un audience mapper) et un mapper may_act fixe sur agent-a. Il active aussi le Standard Token Exchange pour agent-b et donne à agent-b les scopes c.read et c.write comme client scopes optionnels. Retenez ce dernier point. Tout l’article tourne autour de lui.
La chaîne d’appels fonctionne#
A lit la card de B, demande à Keycloak exactement les scopes que liste la skill et envoie message:send. B échange le jeton et appelle C. Le jeton délégué décodé garde A comme sub, restreint aud à C, ne porte que c.read et ajoute act pour B.

L’échange que A n’avait pas accordé#
Maintenant B demande c.write. Le jeton de A n’a pas c.write. Voici la requête, avec des variables :
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.writeKeycloak émet le jeton. sub est A, act désigne B, scope est c.write. C vérifie la signature, l’audience, le claim act et le scope qu’exige sa skill d’écriture, puis ajoute la note.

J’ai exécuté toute la séquence quatre fois sur un Keycloak 26.8.2 neuf, deux fois avec les scripts du lab et deux fois avec ceux de cet article, et j’ai obtenu le même résultat à chaque fois.
Le contrôle : B possède c.write#
Avant d’appeler cela une escalade, j’ai vérifié à qui appartient le droit utilisé. Dans mon realm, B a c.write comme scope optionnel à lui. C’est moi qui l’y ai mis. B n’a donc pas obtenu quelque chose qu’il n’aurait jamais dû avoir. J’ai retiré c.write des scopes optionnels de B et répété le même échange.

Cela règle un point. B ne peut pas aller au-delà de ce qu’il possède, et il n’y a pas de bug au sens d’un contournement. Ce qui se perd est autre chose : le scope du nouveau jeton est borné par la réserve de scopes de B et non par le jeton de A. A avait dit « lecture », et un saut plus loin cela ne signifiait plus rien. La RFC 8693 laisse ce choix au serveur : scope est « the desired scope of the requested security token » et ses valeurs sont « service specific » (section 2.1). Rien n’impose que le résultat soit un sous-ensemble du subject token.
Pour les agents, cela compte parce que C journalise sub A et act B. Celui qui lit le journal voit « A a écrit une note ». A n’y a jamais consenti.
Borner l’échange avec la politique de downscope#
Keycloak a pour cela un executor de client policy : downscope-assertion-grant-enforcer. Il limite les scopes du nouveau jeton à ceux déjà présents dans le subject token et répond invalid_scope sinon. Il ne demande aucune configuration. Je l’ai appliqué à tous les clients du realm avec une seule politique.
{"profiles":[{"name":"downscope-only","description":"exchange can narrow, never widen",
"executors":[{"executor":"downscope-assertion-grant-enforcer","configuration":{}}]}]}Avec c.write de nouveau chez B et la politique active, l’échange est refusé. L’échange légitime avec c.read fonctionne toujours.

La dernière ligne de cette sortie est la note ajoutée par l’essai standard. Elle reste jusqu’au redémarrage de C.
Ce que C doit aussi vérifier#
La politique vit sur le serveur d’autorisation. C ne devrait pas dépendre uniquement d’elle.
- Exigez le claim
actet comparezact.client_idaux agents que vous attendez. Mon C répond 403 sans lui. - Vérifiez le scope par skill. Mon C exige
c.readpour lire etc.writepour écrire. - Vérifiez
aud. Un jeton pour B est refusé par C avec un 401. - Ne traitez pas
may_actcomme une preuve. Quand B a présenté le jeton de C comme acteur, Keycloak a refusé avec un message sur l’audience. Je n’ai pas vérifié s’il compare l’acteur àmay_act.
Pièges#
- L’enforcer et un audience mapper au niveau du client. Dans ma première configuration, l’audience de C se trouvait dans un mapper sur le client B. Avec l’enforcer actif, chaque échange échouait avec « Requested audience not available: agent-c ». Déplacer le mapper sur les scopes
c.readetc.writea réglé le problème. Je ne sais pas pourquoi. Testez dans votre propre realm. - L’audience via les scopes a un effet de bord.
c.readporte l’audience de C, donc le jeton de A aaudB et C. Ce qui empêche A de l’utiliser chez C, c’est l’exigenceact, pas l’audience. - L’erreur sur le mauvais acteur est vague. Le client voit
access_deniedet « Client is not within the token audience ». Le journal d’événements de Keycloak nomme l’acteur. may_actest fixe dans mon realm. Dans un vrai système, il devrait venir d’une politique et vivre avec le jeton.
Ce que je n’ai pas exécuté#
Je n’ai exécuté que Keycloak 26.8.2. Je n’ai testé ni Entra on-behalf-of, ni Okta, ni Auth0, et je n’affirme donc rien sur la façon dont ils bornent le scope dans un échange. Un seul saut de délégation : pas de chaîne act imbriquée. Pas de tâches, de streaming ni d’Agent Cards signées, pas de TLS ni de jetons liés à l’émetteur. Pas d’utilisateur dans la chaîne : le sujet est le service account de l’agent A. Les agents sont mes propres programmes Flask et leurs client secrets sont des valeurs statiques de laboratoire.
Les images de terminal ont été redessinées à partir de la sortie enregistrée des essais, avec les ids remplacés par des variables. Rien ici n’est un identifiant réel.
Pour les standards qui sous-tendent tout cela, voir ID-JAG expliqué et pourquoi un serveur MCP ne doit pas relayer les jetons.
Refaire ce lab#
Environ 40 minutes sur un portable : un Keycloak local avec deux fonctions en préversion, un script pour le realm, trois petits agents en Python et trois échanges : standard, de contrôle et avec la politique de downscope. Ouvrez chaque étape, copiez les blocs et comparez votre résultat avec celui attendu.
Chaque valeur entre chevrons est un espace réservé pour votre environnement de test. Rien sur cette page n’est un identifiant ou un secret réel.
Définissez vos variables une seule fois
# 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>' Étapes terminées : 0 sur 8
Étape 1Démarrer Keycloak avec les fonctions de délégation
Objectif. Lancez un serveur d’autorisation local avec token-exchange-delegation et parameterized-scopes, les deux fonctions en préversion qui ajoutent le claim act.
Prérequis
- Keycloak 26.8.2 décompressé et un JDK 21 ; curl et Python 3.10 ou plus récent
- Port 8080 libre ; gardez ce terminal ouvert et utilisez-en un second pour les étapes suivantes
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 Résultat attendu
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 Étape 2Créer le realm, les clients et le claim may_act
Objectif. Créez le realm a2a : trois clients avec des comptes de service, trois scopes avec audience et un mapper qui place may_act dans le jeton de A. B reçoit c.read et c.write comme scopes optionnels.
Prérequis
- Le bloc env défini dans ce terminal ; Keycloak de l’étape précédente toujours en cours
- Le script prend environ une minute car il réduit les scopes par défaut de chaque client
#!/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" chmod +x kc-realm.sh
./kc-realm.sh 2>&1 | grep -v "^Created\|^Logging" Résultat attendu
realm a2a ready Étape 3Enregistrer et démarrer l’agent B et l’agent C
Objectif. Quatre petits fichiers Python : une bibliothèque commune, l’agent C (notes, n’accepte que des jetons délégués), l’agent B (fait l’échange) et l’agent A (l’appelant). Démarrez B et C et lisez l’Agent Card de C.
Prérequis
- Python 3.10 ou plus récent ; ports 19402 et 19403 libres
- Enregistrez les quatre fichiers dans un dossier, le même que kc-realm.sh
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) 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) 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) 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)) 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'])" Résultat attendu
agent-c notes
['keycloak']
[{'schemes': {'keycloak': {'list': ['c.read']}}}] Étape 4Appeler la chaîne en tant qu’agent A
Objectif. A lit la card de B, demande à Keycloak les scopes listés par la skill et envoie un message. B échange le jeton de A contre un jeton pour C et lit les notes.
Prérequis
- Étapes 1 à 3 terminées, dans le même environnement virtuel
python3 agent_a.py Résultat attendu
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 Étape 5Demander c.write sur un Keycloak standard
Objectif. B échange le jeton de A et demande c.write. Le jeton de A n’a que c.read. Lisez d’abord les scopes optionnels de B, puis regardez ce que Keycloak émet et ce que C en fait.
Prérequis
- Étapes 1 à 4 terminées ; c’est la configuration standard, sans politique
- Enregistrez escal.py depuis le bloc ci-dessous à côté des autres fichiers
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']}") 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 Résultat attendu
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 Étape 6Contrôle : retirer c.write à B
Objectif. Retirez c.write des scopes optionnels de B et répétez le même échange. S’il échoue, B utilisait un droit qu’il détient. Remettez ensuite le scope.
Prérequis
- Étape 5 terminée
- Les commandes se reconnectent, tout terminal avec le bloc env convient
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 Résultat attendu
exchange refused: invalid_scope - Invalid scopes: c.write Étape 7Activer la politique de downscope
Objectif. Ajoutez une client policy avec l’executor downscope-assertion-grant-enforcer, puis répétez l’échange avec c.write et l’échange légitime avec c.read.
Prérequis
- Étape 6 terminée, avec c.write de nouveau sur B
#!/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" chmod +x kc-downscope.sh
./kc-downscope.sh
python3 escal.py c.write
python3 escal.py c.read Résultat attendu
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 Étape 8Nettoyage
Objectif. Arrêtez les agents et Keycloak, supprimez le dossier de données de Keycloak et les journaux, et retirez les secrets du lab de l’environnement.
Prérequis
- Appuyez d’abord sur Ctrl+C dans le terminal qui exécute Keycloak
- Le dossier Keycloak est celui que vous avez décompressé uniquement pour ce lab
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" Résultat attendu
agents stopped Sources#
Discuter de cet article#
Utile ? Partagez-le et dites-moi ce que vous en pensez.
Cet article en Markdown · RSS · JSON feed
Les nouveaux articles par e-mail
Un e-mail par semaine avec les nouveaux articles et labs. Désinscription à tout moment.
Votre adresse est conservée chez Kit, le service qui envoie les e-mails. Détails