iamops.dev
Argo sur X Flux RSS
FRFrançais

Labs Technique 8 min de lecture

Imposer le downscoping dans le token exchange pour les appels entre agents

Lab Keycloak pour agents A2A : le jeton que B obtient pour C suit les scopes de B, pas ceux de A, sans downscoping imposé. Essai standard, contrôle, correctif.

Deux captures de mon lab A2A sur Keycloak : l'échange standard où l'agent B obtient pour l'agent C un jeton avec le scope c.write alors que A n'avait que c.read, et le même échange refusé avec invalid_scope quand la politique de downscope est active.
En brefQuand l'agent B appelle l'agent C pour le compte de l'agent A, B…
  • 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 8 étapes

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.

Aller aux étapes

Comment ça marche

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 claim may_act dans 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_token et le sien comme actor_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
Diagramme de séquence : l'agent A lit l'Agent Card de B, obtient un jeton de Keycloak, appelle B, et B l'échange contre un jeton délégué avec claim act avant d'appeler C.
La chaîne. Les étapes 1 à 4 sont l'appel de B par A. Les étapes 5 à 7 montrent B qui transforme le jeton de A en jeton délégué. Les étapes 8 à 10 sont l'appel de C.

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.

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

Keycloak 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 ».

Sortie de terminal : Keycloak 26.8.2 démarre avec les fonctions en préversion parameterized-scopes et token-exchange-delegation activées, puis le script du realm signale realm a2a ready.
Fonctions et realm. Keycloak 26.8.2 avec deux fonctions en préversion actives, puis le script du realm.

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.

Sortie de terminal : l'agent A lit l'Agent Card de B, demande les scopes agent-b et c.read et reçoit de B une réponse 200 qui résume deux notes conservées par C.
Le chemin légitime. A demande à B de résumer les notes. B échange le jeton de A et les lit chez C.

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 :

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

Sortie de terminal sur Keycloak standard : l'agent B liste c.write parmi ses scopes optionnels, le jeton de A a le scope agent-b c.read, le jeton obtenu par B pour l'agent C a le scope c.write avec act agent-b, et C répond que la note a été ajoutée.
Keycloak standard. Le jeton de A dit c.read. Le jeton pour C dit c.write. C ajoute la note. Les ids sont remplacés par des variables.

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.

Sortie de terminal de l'essai de contrôle : après la suppression de c.write des client scopes optionnels de l'agent B, le même échange est refusé avec invalid_scope, Invalid scopes: c.write.
Le contrôle. Sans c.write chez B, rien n'est émis. B reste dans ses propres droits.

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.

json
{"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.

Sortie de terminal avec la politique de downscope active : l'échange avec c.write est refusé parce que c.write n'est pas dans le jeton d'accès initial, et l'échange avec c.read renvoie toujours un jeton délégué que C accepte.
Avec la politique. c.write est refusé parce que le jeton de A ne le porte pas. c.read fonctionne toujours. C liste aussi la note de l'essai standard.

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 act et comparez act.client_id aux agents que vous attendez. Mon C répond 403 sans lui.
  • Vérifiez le scope par skill. Mon C exige c.read pour lire et c.write pour écrire.
  • Vérifiez aud. Un jeton pour B est refusé par C avec un 401.
  • Ne traitez pas may_act comme 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.read et c.write a 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.read porte l’audience de C, donc le jeton de A a aud B et C. Ce qui empêche A de l’utiliser chez C, c’est l’exigence act, pas l’audience.
  • L’erreur sur le mauvais acteur est vague. Le client voit access_denied et « Client is not within the token audience ». Le journal d’événements de Keycloak nomme l’acteur.
  • may_act est 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

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>'
É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
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

Résultat attendu

résultat
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
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"

Résultat attendu

résultat
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
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'])"

Résultat attendu

résultat
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
bash · call-chain.sh
python3 agent_a.py

Résultat attendu

résultat
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
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

Résultat attendu

résultat
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
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

Résultat attendu

résultat
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
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

Résultat attendu

résultat
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
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"

Résultat attendu

résultat
agents stopped

Sources#

Discuter de cet article#

Utile ? Partagez-le et dites-moi ce que vous en pensez.

Suivre sur X

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

Articles et labs liés