# Imponer el downscoping en el token exchange para llamadas entre agentes

> Lab de Keycloak para agentes A2A: el token que B obtiene para C sigue los scopes de B, no los de A, sin downscoping impuesto. Prueba, control y solución.

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

## En resumen

- Cuando el agente B llama al agente C en nombre del agente A, B cambia el token de A por uno nuevo. En Keycloak 26.8.2 el scope de ese token nuevo sigue los scopes de B, no el token que entregó A, salvo que impongas el downscoping.
- En mi prueba A tenía c.read, B tenía c.write como scope opcional propio, y el intercambio de B devolvió un token para A con c.write. El agente C aceptó una escritura que A nunca concedió.
- Es B usando un derecho que posee, no B saltándose sus límites. Con c.write retirado a B, el mismo intercambio falla con invalid_scope. Es una lección de configuración, no una vulnerabilidad.
- Una client policy con el executor downscope-assertion-grant-enforcer limita el intercambio a los scopes de A. El agente C debería exigir también el claim act y comprobar el scope de cada skill.
- Solo probé Keycloak. A2A 1.0.0 deja la autorización a la implementación, y la Agent Card no tiene ningún campo para el token exchange.

A2A 1.0.0 es la versión actual del protocolo Agent2Agent. Exige que un servidor autentique cada petición y deja la autorización a la implementación. No dice qué pasa cuando el agente B llama al agente C en nombre del agente A. Esa parte es OAuth corriente, y la herramienta habitual es el token exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)). Monté una cadena pequeña sobre un Keycloak local y me hice una sola pregunta: ¿el token que B obtiene para C se queda dentro de lo que A entregó?

No, salvo que le pidas a Keycloak que lo imponga. Este artículo trata de ese ajuste. Si has leído mi [primer lab de token exchange con Keycloak](https://iamops.dev/es/keycloak-token-exchange-rfc-8693/), este continúa desde la trampa «sin claim act» y añade la delegación.

## Qué muestra este lab

Tres agentes y un servidor de autorización, todos en localhost.

- **A** es quien llama. Tiene un token con scope `agent-b c.read`. Un claim `may_act` en ese token señala a B como la parte autorizada a actuar por él.
- **B** es un agente intermedio. Recibe la llamada de A y luego pide a Keycloak un token para llamar a C, con el token de A como `subject_token` y el suyo como `actor_token`.
- **C** es un pequeño agente de notas con una skill de lectura y otra de escritura. Solo acepta tokens delegados y comprueba el scope de cada skill.

| Cliente | Papel | Scopes que puede pedir en un intercambio |
| --- | --- | --- |
| `agent-a` | Quien llama, service account | `agent-b` por defecto, `c.read` si lo pide |
| `agent-b` | Agente intermedio, hace el intercambio | `c.read` y `c.write`, ambos opcionales |
| `agent-c` | Agente de notas, solo audience | ninguno |

![Diagrama de secuencia: el agente A lee la Agent Card de B, obtiene un token de Keycloak, llama a B, y B lo cambia por un token delegado con claim act antes de llamar a C.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/00-flow.webp)

*La cadena. Los pasos 1 a 4 son A llamando a B. Los pasos 5 a 7 muestran a B convirtiendo el token de A en un token delegado. Los pasos 8 a 10 son la llamada a C.*

Cada agente publica una Agent Card en `/.well-known/agent-card.json` con un esquema de seguridad `oauth2` y los scopes por skill. El esquema puede decir `clientCredentials` y nada más cercano al token exchange: un objeto `OAuthFlows` contiene exactamente un flujo, y no existe un flujo de intercambio. Por eso la card de C lo dice en el texto de su descripción, y quien llama debe leerlo.

## Configuración

Keycloak 26.8.2 desde el zip, Java 21, modo desarrollo. El standard token exchange viene activo por defecto en la 26.8. La delegación, es decir los claims `act` y `may_act`, no. Necesita dos funciones en vista previa.

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

Keycloak imprime al arrancar las funciones en vista previa activadas. Las activé juntas y no las probé una por una. Sin ellas mi cadena falla: Keycloak rechaza en un intercambio simple cualquier subject token que lleve `may_act`, con «Subject token with a delegation claim is not allowed for standard token exchange».

![Salida de terminal: Keycloak 26.8.2 arranca con las funciones en vista previa parameterized-scopes y token-exchange-delegation activadas, y luego el script del realm informa realm a2a ready.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/01-features.webp)

*Funciones y realm. Keycloak 26.8.2 con dos funciones en vista previa activas, y luego el script del realm.*

El script del realm crea los tres clientes con service accounts, los scopes `agent-b`, `c.read` y `c.write` (cada uno con un audience mapper) y un mapper `may_act` fijo en `agent-a`. También activa el Standard Token Exchange para `agent-b` y da a `agent-b` los scopes `c.read` y `c.write` como client scopes opcionales. Recuerda este último punto. Todo el artículo gira en torno a él.

## La cadena de llamadas funciona

A lee la card de B, pide a Keycloak exactamente los scopes que lista la skill y envía `message:send`. B cambia el token y llama a C. El token delegado decodificado conserva a A como `sub`, restringe `aud` a C, lleva solo `c.read` y añade `act` para B.

![Salida de terminal: el agente A lee la Agent Card de B, pide los scopes agent-b y c.read y recibe de B una respuesta 200 que resume dos notas guardadas por C.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/02-chain.webp)

*El camino legítimo. A pide a B que resuma las notas. B cambia el token de A y las lee en C.*

## El intercambio que A nunca concedió

Ahora B pide `c.write`. El token de A no tiene `c.write`. Esta es la petición, con marcadores:

```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 emite el token. `sub` es A, `act` señala a B, `scope` es `c.write`. C comprueba la firma, la audience, el claim `act` y el scope que exige su skill de escritura, y añade la nota.

![Salida de terminal en Keycloak estándar: el agente B lista c.write entre sus scopes opcionales, el token de A tiene scope agent-b c.read, el token que B obtiene para el agente C tiene scope c.write con act agent-b, y C responde que la nota se añadió.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/03-stock.webp)

*Keycloak estándar. El token de A dice c.read. El token para C dice c.write. C añade la nota. Los ids están sustituidos por marcadores.*

Ejecuté toda la secuencia cuatro veces sobre un Keycloak 26.8.2 nuevo, dos con los scripts del lab y dos con los de este artículo, y obtuve el mismo resultado cada vez.

## El control: B posee c.write

Antes de llamarlo escalada, comprobé de quién es el derecho que se usa. En mi realm B tiene `c.write` como scope opcional propio. Lo puse yo. Así que B no obtuvo algo que nunca debió tener. Quité `c.write` de los scopes opcionales de B y repetí el mismo intercambio.

![Salida de terminal de la prueba de control: tras eliminar c.write de los client scopes opcionales del agente B, el mismo intercambio es rechazado con invalid_scope, Invalid scopes: c.write.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/04-control.webp)

*El control. Sin c.write en B no se emite nada. B se queda dentro de sus propios derechos.*

Esto aclara una cosa. B no puede ir más allá de lo que posee, y no hay un bug en el sentido de una evasión. Lo que se pierde es otra cosa: el scope del token nuevo lo limita el conjunto de scopes de B y no el token de A. A había dicho «lectura», y un salto después eso ya no significaba nada. La RFC 8693 deja esa decisión al servidor: `scope` es «the desired scope of the requested security token» y sus valores son «service specific» ([sección 2.1](https://www.rfc-editor.org/rfc/rfc8693#section-2.1)). Nada exige que el resultado sea un subconjunto del subject token.

Para los agentes importa porque C registra `sub` A y `act` B. Quien lee el log ve «A escribió una nota». A nunca lo aceptó.

## Acotar el intercambio con la política de downscope

Keycloak tiene para esto un executor de client policy: `downscope-assertion-grant-enforcer`. Limita los scopes del token nuevo a los que ya están en el subject token y responde `invalid_scope` en otro caso. No necesita configuración. Lo apliqué a todos los clientes del realm con una sola política.

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

Con `c.write` de nuevo en B y la política activa, el intercambio se rechaza. El intercambio legítimo con `c.read` sigue funcionando.

![Salida de terminal con la política de downscope activa: el intercambio con c.write se rechaza porque c.write no está en el token de acceso inicial, y el intercambio con c.read sigue devolviendo un token delegado que C acepta.](https://iamops.dev/media/enforce-downscoping-token-exchange-a2a/05-enforcer.webp)

*Con la política. c.write se rechaza porque el token de A no lo lleva. c.read sigue funcionando. C también lista la nota de la prueba estándar.*

La última línea de esa salida es la nota añadida por la prueba estándar. Se queda hasta que reinicies C.

## Qué debe comprobar también C

La política vive en el servidor de autorización. C no debería depender solo de ella.

- Exige el claim `act` y compara `act.client_id` con los agentes que esperas. Mi C responde 403 sin él.
- Comprueba el scope por skill. Mi C exige `c.read` para leer y `c.write` para escribir.
- Comprueba `aud`. Un token para B lo rechaza C con un 401.
- No trates `may_act` como una prueba. Cuando B presentó el token de C como actor, Keycloak lo rechazó con un mensaje sobre la audience. No comprobé si compara el actor con `may_act`.

## Trampas

- **El enforcer y un audience mapper a nivel de cliente.** En mi primera configuración la audience de C estaba en un mapper del cliente B. Con el enforcer activo, cada intercambio fallaba con «Requested audience not available: agent-c». Mover el mapper a los scopes `c.read` y `c.write` lo arregló. No sé por qué. Pruébalo en tu propio realm.
- **La audience por scopes tiene un efecto secundario.** `c.read` lleva la audience de C, así que el token de A tiene `aud` B y C. Lo que impide a A usarlo en C es el requisito de `act`, no la audience.
- **El error con el actor equivocado es vago.** El cliente ve `access_denied` y «Client is not within the token audience». El registro de eventos de Keycloak nombra al actor.
- **`may_act` es fijo en mi realm.** En un sistema real debería salir de una política y viajar con el token.

## Lo que no ejecuté

Solo ejecuté Keycloak 26.8.2. No probé Entra on-behalf-of, Okta ni Auth0, así que no afirmo nada sobre cómo acotan el scope en un intercambio. Un solo salto de delegación: sin cadena `act` anidada. Sin tareas, streaming ni Agent Cards firmadas, sin TLS ni tokens ligados al emisor. Sin usuario en la cadena: el sujeto es el service account del agente A. Los agentes son programas Flask míos y sus client secrets son valores estáticos de laboratorio.

*Las imágenes de terminal se redibujaron a partir de la salida guardada de las ejecuciones, con los ids sustituidos por marcadores. Nada de esto es una credencial real.*

Para los estándares que hay detrás, mira [ID-JAG explicado](https://iamops.dev/es/id-jag-explained/) y [por qué un servidor MCP no debe reenviar tokens](https://iamops.dev/es/mcp-server-no-token-passthrough/).

## Repite este lab

Unos 40 minutos en un portátil: un Keycloak local con dos funciones en vista previa, un script para el realm, tres agentes pequeños en Python y tres intercambios: estándar, de control y con la política de downscope. Abre cada paso, copia los bloques y compara tu salida con la esperada.

Cada valor entre corchetes angulares es un marcador para tu entorno de prueba. Nada en esta página es un identificador o secreto real.

**Define tus variables una sola vez** `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>'
```

### Paso 1: Inicia Keycloak con las funciones de delegación

**Objetivo.** Ejecuta un servidor de autorización local con token-exchange-delegation y parameterized-scopes, las dos funciones en vista previa que añaden el claim act.

**Requisitos**

- Keycloak 26.8.2 descomprimido y un JDK 21; curl y Python 3.10 o superior
- Puerto 8080 libre; deja abierta esta terminal y usa una segunda para los pasos siguientes

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

**Salida esperada**

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

### Paso 2: Crea el realm, los clientes y el claim may_act

**Objetivo.** Crea el realm a2a: tres clientes con cuentas de servicio, tres scopes con audiencia y un mapper que pone may_act en el token de A. B recibe c.read y c.write como scopes opcionales.

**Requisitos**

- El bloque env definido en esta terminal; Keycloak del paso anterior sigue en marcha
- El script tarda aproximadamente un minuto porque recorta los scopes por defecto de cada cliente

`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"
```

**Salida esperada**

```text
realm a2a ready
```

### Paso 3: Guarda e arranca el agente B y el agente C

**Objetivo.** Cuatro archivos Python pequeños: una biblioteca común, el agente C (notas, solo acepta tokens delegados), el agente B (hace el intercambio) y el agente A (quien llama). Arranca B y C y lee la Agent Card de C.

**Requisitos**

- Python 3.10 o superior; puertos 19402 y 19403 libres
- Guarda los cuatro archivos en una carpeta, la misma 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'])"
```

**Salida esperada**

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

### Paso 4: Llama a la cadena como agente A

**Objetivo.** A lee la card de B, pide a Keycloak los scopes que lista la skill y envía un mensaje. B cambia el token de A por un token para C y lee las notas.

**Requisitos**

- Pasos 1 a 3 hechos, en el mismo entorno virtual

`call-chain.sh` (bash)

```bash
python3 agent_a.py
```

**Salida esperada**

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

### Paso 5: Pide c.write en Keycloak estándar

**Objetivo.** B cambia el token de A y pide c.write. El token de A solo tiene c.read. Lee primero los scopes opcionales de B y mira después qué emite Keycloak y qué hace C con él.

**Requisitos**

- Pasos 1 a 4 hechos; es la configuración estándar, aún sin política
- Guarda escal.py del bloque de abajo junto a los demás archivos

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

**Salida esperada**

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

### Paso 6: Control: quita c.write a B

**Objetivo.** Quita c.write de los scopes opcionales de B y repite el mismo intercambio. Si falla, B usaba un derecho que tiene. Después vuelve a poner el scope.

**Requisitos**

- Paso 5 hecho
- Los comandos vuelven a iniciar sesión, vale cualquier terminal con el bloque env

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

**Salida esperada**

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

### Paso 7: Activa la política de downscope

**Objetivo.** Añade una client policy con el executor downscope-assertion-grant-enforcer y repite después el intercambio con c.write y el legítimo con c.read.

**Requisitos**

- Paso 6 hecho, con c.write de nuevo en 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
```

**Salida esperada**

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

### Paso 8: Limpieza

**Objetivo.** Detén los agentes y Keycloak, borra la carpeta de datos de Keycloak y los logs, y quita los secretos del lab del entorno.

**Requisitos**

- Pulsa antes Ctrl+C en la terminal que ejecuta Keycloak
- La carpeta de Keycloak es la que descomprimiste solo para este 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"
```

**Salida esperada**

```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)
