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

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

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

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](https://www.rfc-editor.org/rfc/rfc8693)). 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](https://iamops.dev/fr/keycloak-token-exchange-rfc-8693/), 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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/00-flow.webp)

*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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/01-features.webp)

*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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/02-chain.webp)

*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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/03-stock.webp)

*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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/04-control.webp)

*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](https://www.rfc-editor.org/rfc/rfc8693#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.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/05-enforcer.webp)

*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é](https://iamops.dev/fr/id-jag-explained/) et [pourquoi un serveur MCP ne doit pas relayer les jetons](https://iamops.dev/fr/mcp-server-no-token-passthrough/).

## 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** `env.sh` (bash)

```bash
# Paste into every terminal you use for this lab. Replace each <PLACEHOLDER> with a throwaway value of your own.
export KC_HOME='<KEYCLOAK_DIR>'          # the unpacked keycloak-26.8.2 folder
export JAVA_HOME='<JDK_DIR>'             # a JDK 21
export KC_URL="http://localhost:8080"
export KC_ADMIN_USER="admin"
export KC_ADMIN_PASSWORD='<ADMIN_PASSWORD>'
export AGENT_A_SECRET='<AGENT_A_SECRET>'
export AGENT_B_SECRET='<AGENT_B_SECRET>'
export AGENT_C_SECRET='<AGENT_C_SECRET>'
```

### Étape 1: Dé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

`start-keycloak.sh` (bash)

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

**Résultat attendu**

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

### Étape 2: Cré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

`kc-realm.sh` (bash)

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

`create-realm.sh` (bash)

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

**Résultat attendu**

```text
realm a2a ready
```

### Étape 3: Enregistrer 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

`a2alib.py` (python)

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

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


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


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


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


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


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


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


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


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


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


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


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


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


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

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

`agent_c.py` (python)

```python
import os
from a2alib import *

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

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

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

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

`agent_b.py` (python)

```python
import os
from a2alib import *

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

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

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

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

`agent_a.py` (python)

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

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

`start-agents.sh` (bash)

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

**Résultat attendu**

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

### Étape 4: Appeler 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

`call-chain.sh` (bash)

```bash
python3 agent_a.py
```

**Résultat attendu**

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

### Étape 5: Demander 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

`escal.py` (python)

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

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

`stock-exchange.sh` (bash)

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

**Résultat attendu**

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

### Étape 6: Contrô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

`control.sh` (bash)

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

**Résultat attendu**

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

### Étape 7: Activer 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

`kc-downscope.sh` (bash)

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

`downscope.sh` (bash)

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

**Résultat attendu**

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

### Étape 8: Nettoyage

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

`cleanup.sh` (bash)

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

**Résultat attendu**

```text
agents stopped
```


## Sources

- [A2A Protocol specification 1.0.0](https://a2a-protocol.org/latest/specification/)
- [RFC 8693: OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693)
- [Keycloak documentation: Configuring and using token exchange](https://www.keycloak.org/securing-apps/token-exchange)
- [RFC 6749: The OAuth 2.0 Authorization Framework, client credentials grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)
