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.
Repite este lab
Escribí este lab para que puedas repetirlo tú mismo. Cada paso tiene los comandos para copiar y la salida que obtuve yo, y puedes marcarlo como hecho. Las marcas se quedan solo en este navegador.
Copia un prompt listo para Claude Code, Cursor, Codex o cualquier agente de código. Solo para entornos de prueba.
Mostrar el prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Imponer el downscoping en el token exchange para llamadas entre agentes Read the whole lab here (Markdown): https://iamops.dev/es/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 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). 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, 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 claimmay_acten 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_tokeny el suyo comoactor_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 |

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.
"$KC_HOME/bin/kc.sh" start-dev --http-port 8080 --features=token-exchange-delegation,parameterized-scopesKeycloak 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».

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.

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:
curl -s "$KC_URL/realms/a2a/protocol/openid-connect/token" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d client_id=agent-b -d "client_secret=$AGENT_B_SECRET" \
-d subject_token="$A_TOKEN" -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d actor_token="$B_TOKEN" -d actor_token_type=urn:ietf:params:oauth:token-type:access_token \
-d audience=agent-c -d scope=c.writeKeycloak 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.

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.

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

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
acty comparaact.client_idcon los agentes que esperas. Mi C responde 403 sin él. - Comprueba el scope por skill. Mi C exige
c.readpara leer yc.writepara escribir. - Comprueba
aud. Un token para B lo rechaza C con un 401. - No trates
may_actcomo 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 conmay_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.readyc.writelo arregló. No sé por qué. Pruébalo en tu propio realm. - La audience por scopes tiene un efecto secundario.
c.readlleva la audience de C, así que el token de A tieneaudB y C. Lo que impide a A usarlo en C es el requisito deact, no la audience. - El error con el actor equivocado es vago. El cliente ve
access_deniedy «Client is not within the token audience». El registro de eventos de Keycloak nombra al actor. may_actes 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 y por qué un servidor MCP no debe reenviar tokens.
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
# 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>' 0 de 8 pasos hechos
Paso 1Inicia 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
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
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 2Crea 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
#!/usr/bin/env bash
# Realm "a2a": three agents as clients with service accounts, scopes with audiences, and a may_act claim that names the actor.
set -euo pipefail
: "${KC_HOME:?}" "${JAVA_HOME:?}" "${KC_ADMIN_PASSWORD?}" "${AGENT_A_SECRET:?}" "${AGENT_B_SECRET:?}" "${AGENT_C_SECRET:?}"
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "${KC_URL:-http://localhost:8080}" --realm master --user "${KC_ADMIN_USER:-admin}" --password "$KC_ADMIN_PASSWORD" >/dev/null
$KCADM create realms -s realm=a2a -s enabled=true -s sslRequired=none >/dev/null
scope() { # name audience
$KCADM create client-scopes -r a2a -s name="$1" -s protocol=openid-connect -s 'attributes."include.in.token.scope"=true' >/dev/null
local id; id=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, -v n="$1" '$2==n{print $1}')
$KCADM create client-scopes/$id/protocol-mappers/models -r a2a -s name="aud-$2" -s protocol=openid-connect -s protocolMapper=oidc-audience-mapper \
-s "config.\"included.client.audience\"=$2" -s 'config."access.token.claim"=true' -s 'config."id.token.claim"=false' >/dev/null
echo "$id"
}
S_B=$(scope agent-b agent-b); S_CR=$(scope c.read agent-c); S_CW=$(scope c.write agent-c)
agent() { # client id, secret
$KCADM create clients -r a2a -s clientId="$1" -s secret="$2" -s publicClient=false -s serviceAccountsEnabled=true \
-s standardFlowEnabled=false -s directAccessGrantsEnabled=false >/dev/null
$KCADM get clients -r a2a -q clientId="$1" --fields id --format csv --noquotes
}
A=$(agent agent-a "$AGENT_A_SECRET"); B=$(agent agent-b "$AGENT_B_SECRET"); C=$(agent agent-c "$AGENT_C_SECRET")
# keep the tokens small: drop the default profile, email and roles scopes from every agent
for CID in $A $B $C; do
for SN in roles profile email web-origins acr basic; do
SID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, -v n="$SN" '$2==n{print $1}')
[ -n "$SID" ] && $KCADM delete clients/$CID/default-client-scopes/$SID -r a2a >/dev/null 2>&1 || true
done
done
# agent-b performs the exchange
$KCADM update clients/$B -r a2a -s 'attributes."standard.token.exchange.enabled"=true' >/dev/null
SA_B=$($KCADM get clients/$B/service-account-user -r a2a --fields id --format csv --noquotes)
# agent-a: may call agent-b by default, may add c.read when it asks for it
$KCADM update clients/$A/default-client-scopes/$S_B -r a2a >/dev/null
$KCADM update clients/$A/optional-client-scopes/$S_CR -r a2a >/dev/null
# the claim value is JSON, so pass the mapper as a file; kcadm -s cannot carry nested quotes
MAP=$(mktemp)
cat > "$MAP" <<JSON
{"name":"may-act-agent-b","protocol":"openid-connect","protocolMapper":"oidc-hardcoded-claim-mapper",
"config":{"claim.name":"may_act","claim.value":"{\"sub\":\"$SA_B\",\"client_id\":\"agent-b\"}","jsonType.label":"JSON",
"access.token.claim":"true","id.token.claim":"false"}}
JSON
$KCADM create clients/$A/protocol-mappers/models -r a2a -f "$MAP" >/dev/null; rm -f "$MAP"
# agent-b: its own token is the actor token; c.read and c.write are optional scopes it can ask for in an exchange
$KCADM update clients/$B/optional-client-scopes/$S_CR -r a2a >/dev/null
$KCADM update clients/$B/optional-client-scopes/$S_CW -r a2a >/dev/null
echo "realm a2a ready" chmod +x kc-realm.sh
./kc-realm.sh 2>&1 | grep -v "^Created\|^Logging" Salida esperada
realm a2a ready Paso 3Guarda 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
import json, os, urllib.error, urllib.parse, urllib.request, uuid
import jwt
from flask import Flask, Response, request
KC_URL = os.environ.get("KC_URL", "http://localhost:8080")
ISS = f"{KC_URL}/realms/a2a"
TOKEN_URL = f"{ISS}/protocol/openid-connect/token"
JWKS = jwt.PyJWKClient(f"{ISS}/protocol/openid-connect/certs")
MEDIA = "application/a2a+json"
AT = "urn:ietf:params:oauth:token-type:access_token"
class Reject(Exception):
def __init__(self, http, status, reason, message):
self.http, self.status, self.reason, self.message = http, status, reason, message
def error_body(r):
return {"error": {"code": r.http, "status": r.status, "message": r.message,
"details": [{"@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": r.reason, "domain": "a2a-protocol.org"}]}}
def verify(auth_header, my_audience):
if not auth_header or not auth_header.lower().startswith("bearer "):
raise Reject(401, "UNAUTHENTICATED", "MISSING_TOKEN", "bearer token required")
token = auth_header[7:].strip()
try:
key = JWKS.get_signing_key_from_jwt(token).key
return jwt.decode(token, key, algorithms=["RS256"], audience=my_audience, issuer=ISS,
options={"require": ["exp", "iss", "aud", "sub"]})
except jwt.InvalidAudienceError:
raise Reject(401, "UNAUTHENTICATED", "WRONG_AUDIENCE", f"token is not meant for {my_audience}")
except jwt.PyJWTError as e:
raise Reject(401, "UNAUTHENTICATED", "INVALID_TOKEN", f"token rejected: {type(e).__name__}")
def scopes(claims):
return set((claims.get("scope") or "").split())
def secret_of(client_id):
return os.environ[client_id.upper().replace("-", "_") + "_SECRET"]
def post_form(data):
req = urllib.request.Request(TOKEN_URL, data=urllib.parse.urlencode(data).encode())
try:
with urllib.request.urlopen(req) as r:
return json.load(r)
except urllib.error.HTTPError as e:
return {"http_status": e.code, **json.load(e)}
def client_credentials(client_id, scope=None):
d = {"grant_type": "client_credentials", "client_id": client_id, "client_secret": secret_of(client_id)}
if scope:
d["scope"] = scope
return post_form(d)
def exchange(client_id, subject_token, actor_token, audience, scope):
d = {"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "client_id": client_id,
"client_secret": secret_of(client_id), "subject_token": subject_token, "subject_token_type": AT,
"audience": audience, "scope": scope}
if actor_token:
d.update(actor_token=actor_token, actor_token_type=AT)
return post_form(d)
def fetch_card(base):
with urllib.request.urlopen(f"{base}/.well-known/agent-card.json") as r:
return json.load(r)
def send_message(base, token, text):
body = {"message": {"messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"text": text}]}}
h = {"Content-Type": MEDIA, "A2A-Version": "1.0"}
if token:
h["Authorization"] = f"Bearer {token}"
req = urllib.request.Request(f"{base}/message:send", data=json.dumps(body).encode(), headers=h, method="POST")
try:
with urllib.request.urlopen(req) as r:
return r.status, json.load(r)
except urllib.error.HTTPError as e:
return e.code, json.load(e)
def reply(text):
return {"message": {"messageId": str(uuid.uuid4()), "role": "ROLE_AGENT", "parts": [{"text": text}]}}
def claims_unverified(token):
import base64
p = token.split(".")[1]
return json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4)))
def serve(name, port, card, handle):
app = Flask(name)
out = lambda obj, status=200: Response(json.dumps(obj), status=status, mimetype=MEDIA)
app.get("/.well-known/agent-card.json")(lambda: out(card))
@app.post("/message:send")
def send():
try:
return out(reply(handle(request)))
except Reject as r:
print(f"AUDIT {name}: DENIED {r.http} {r.reason}", flush=True)
return out(error_body(r), r.http)
app.run(port=port) import os
from a2alib import *
PORT = int(os.environ.get("C_PORT", "19403"))
NOTES = ["note 1: quarterly review is on Thursday", "note 2: renew the staging certificate"]
need = lambda s: [{"schemes": {"keycloak": {"list": [s]}}}]
CARD = {
"name": "agent-c notes", "description": "Keeps a short list of notes. Reads and writes need a delegated token.", "version": "1.0.0",
"supportedInterfaces": [{"url": f"http://localhost:{PORT}", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}],
"capabilities": {"streaming": False, "pushNotifications": False},
"defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"],
"securitySchemes": {"keycloak": {"oauth2SecurityScheme": {
"description": "Tokens come from Keycloak via RFC 8693 token exchange, with an actor token. The scheme types below cannot say that, so this text does.",
"oauth2MetadataUrl": f"{ISS}/.well-known/oauth-authorization-server",
"flows": {"clientCredentials": {"tokenUrl": TOKEN_URL, "scopes": {"c.read": "read notes", "c.write": "add notes"}}}}}},
"skills": [
{"id": "read-notes", "name": "Read notes", "description": "Say 'read' to get all notes.", "tags": ["notes"], "securityRequirements": need("c.read")},
{"id": "add-note", "name": "Add a note", "description": "Say 'write: <text>' to add one.", "tags": ["notes"], "securityRequirements": need("c.write")}],
}
def handle(req):
c = verify(req.headers.get("Authorization"), "agent-c")
act = c.get("act") or {}
if act.get("client_id") != "agent-b":
raise Reject(403, "PERMISSION_DENIED", "ACTOR_REQUIRED", "a delegated token from agent-b is required")
text = req.get_json(force=True)["message"]["parts"][0]["text"].strip()
skill = "c.write" if text.startswith("write:") else "c.read"
if skill not in scopes(c):
raise Reject(403, "PERMISSION_DENIED", "INSUFFICIENT_SCOPE", f"skill needs scope {skill}")
print(f"AUDIT c: sub={c['sub'][:8]} actor={act['client_id']} scope='{c.get('scope')}' skill={skill}", flush=True)
if skill == "c.write":
NOTES.append(text[6:].strip())
return f"added, {len(NOTES)} notes now"
return "\n".join(NOTES)
serve("c", PORT, CARD, handle) import os
from a2alib import *
PORT, C_BASE = int(os.environ.get("B_PORT", "19402")), os.environ.get("C_BASE", "http://localhost:19403")
need = lambda *s: [{"schemes": {"keycloak": {"list": list(s)}}}]
CARD = {
"name": "agent-b summariser", "description": "Reads the notes through agent C and sums them up.", "version": "1.0.0",
"supportedInterfaces": [{"url": f"http://localhost:{PORT}", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}],
"capabilities": {"streaming": False, "pushNotifications": False},
"defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"],
"securitySchemes": {"keycloak": {"oauth2SecurityScheme": {
"oauth2MetadataUrl": f"{ISS}/.well-known/oauth-authorization-server",
"flows": {"clientCredentials": {"tokenUrl": TOKEN_URL, "scopes": {"agent-b": "call agent B", "c.read": "allow B to read notes for you"}}}}}},
"skills": [{"id": "summarize", "name": "Summarise notes", "description": "Say 'summarize'.", "tags": ["notes"], "securityRequirements": need("agent-b", "c.read")}],
}
def handle(req):
bearer = req.headers.get("Authorization")
c = verify(bearer, "agent-b")
for s in ("agent-b", "c.read"):
if s not in scopes(c):
raise Reject(403, "PERMISSION_DENIED", "INSUFFICIENT_SCOPE", f"skill needs scope {s}")
actor = client_credentials("agent-b")["access_token"]
ex = exchange("agent-b", bearer[7:].strip(), actor, audience="agent-c", scope="c.read")
if "access_token" not in ex:
raise Reject(502, "UNAVAILABLE", "EXCHANGE_FAILED", f"token exchange refused: {ex.get('error_description')}")
print(f"AUDIT b: exchanged for sub={c['sub'][:8]} scope='{ex['scope']}'", flush=True)
code, body = send_message(C_BASE, ex["access_token"], "read")
if code != 200:
raise Reject(502, "UNAVAILABLE", "DOWNSTREAM_REFUSED", f"agent C said {code}")
notes = body["message"]["parts"][0]["text"].splitlines()
return f"{len(notes)} notes. First: {notes[0]}"
serve("b", PORT, CARD, handle) import json, sys
from a2alib import *
B = "http://localhost:19402"
card = fetch_card(B)
skill = card["skills"][0]
want = skill["securityRequirements"][0]["schemes"]["keycloak"]["list"]
flow = card["securitySchemes"]["keycloak"]["oauth2SecurityScheme"]["flows"]["clientCredentials"]
print(f"card says: skill '{skill['id']}' needs scopes {want}, token endpoint {flow['tokenUrl'].split('/realms/')[1]}")
tok = client_credentials("agent-a", " ".join(want))
claims = claims_unverified(tok["access_token"])
print(f"token: aud={claims['aud']} scope='{claims['scope']}' may_act={claims['may_act']['client_id']}")
code, body = send_message(B, tok["access_token"], sys.argv[1] if len(sys.argv) > 1 else "summarize")
print(code, body["message"]["parts"][0]["text"] if code == 200 else json.dumps(body)) python3 -m venv .venv && . .venv/bin/activate
pip install -q "PyJWT==2.15.1" "Flask==3.1.3" "cryptography==50.0.2"
nohup python3 agent_c.py > c.log 2>&1 &
nohup python3 agent_b.py > b.log 2>&1 &
sleep 3
curl -s localhost:19403/.well-known/agent-card.json | python3 -c "import sys,json;c=json.load(sys.stdin);print(c['name']);print(list(c['securitySchemes']));print(c['skills'][0]['securityRequirements'])" Salida esperada
agent-c notes
['keycloak']
[{'schemes': {'keycloak': {'list': ['c.read']}}}] Paso 4Llama 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
python3 agent_a.py Salida esperada
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 5Pide 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
import json, sys
from a2alib import *
scope = sys.argv[1]
KEYS = ("aud", "scope", "azp", "sub", "may_act", "act")
show = lambda t: json.dumps({k: claims_unverified(t)[k] for k in KEYS if k in claims_unverified(t)}, indent=1)
a = client_credentials("agent-a", "agent-b c.read")["access_token"]
b = client_credentials("agent-b")["access_token"]
print("## A's token\n" + show(a))
ex = exchange("agent-b", a, b, "agent-c", scope)
if "access_token" not in ex:
sys.exit(f"exchange refused: {ex['error']} - {ex['error_description']}")
print("## token B got for C\n" + show(ex["access_token"]))
text = "write: evidence note" if scope == "c.write" else "read"
code, body = send_message("http://localhost:19403", ex["access_token"], text)
print("C says:", body["message"]["parts"][0]["text"] if code == 200 else f"{code} {body['error']['details'][0]['reason']}") KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
B_ID=$($KCADM get clients -r a2a -q clientId=agent-b --fields id --format csv --noquotes)
CW_ID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, '$2=="c.write"{print $1}')
$KCADM get clients/$B_ID/optional-client-scopes -r a2a --fields name --format csv --noquotes | tr '\n' ' '; echo
python3 escal.py c.write Salida esperada
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 6Control: 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
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
exchange refused: invalid_scope - Invalid scopes: c.write Paso 7Activa 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
#!/usr/bin/env bash
# Client policy: every token exchange in realm a2a may only carry scopes that were already in the subject token.
set -euo pipefail
: "${KC_HOME:?}" "${JAVA_HOME:?}" "${KC_ADMIN_PASSWORD?}"
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "${KC_URL:-http://localhost:8080}" --realm master --user "${KC_ADMIN_USER:-admin}" --password "$KC_ADMIN_PASSWORD" >/dev/null
TMP=$(mktemp)
cat > "$TMP" <<'JSON'
{"profiles":[{"name":"downscope-only","description":"exchange can narrow, never widen",
"executors":[{"executor":"downscope-assertion-grant-enforcer","configuration":{}}]}]}
JSON
$KCADM update client-policies/profiles -r a2a -f "$TMP"
cat > "$TMP" <<'JSON'
{"policies":[{"name":"all-clients-downscope","description":"applies to every client in the realm","enabled":true,
"conditions":[{"condition":"any-client","configuration":{}}],"profiles":["downscope-only"]}]}
JSON
$KCADM update client-policies/policies -r a2a -f "$TMP"; rm -f "$TMP"
echo "downscope policy active" chmod +x kc-downscope.sh
./kc-downscope.sh
python3 escal.py c.write
python3 escal.py c.read Salida esperada
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 8Limpieza
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
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
agents stopped Fuentes#
Comenta este artículo#
¿Te ha servido? Compártelo y dime qué piensas.
Este artículo en Markdown · RSS · JSON feed
Nuevos artículos por correo
Un correo a la semana con nuevos artículos y labs. Puedes darte de baja cuando quieras.
Tu dirección se guarda en Kit, el servicio que envía los correos. Detalles