iamops.dev
Argo en X Feed RSS
ESEspañol

Labs Técnico 8 min de lectura

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.

Dos capturas de mi lab A2A en Keycloak: el intercambio estándar en el que el agente B obtiene para el agente C un token con scope c.write aunque A solo tenía c.read, y el mismo intercambio rechazado con invalid_scope cuando la política de downscope está activa.
En resumenCuando el agente B llama al agente C en nombre del agente A, B cambia…
  • 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 8 pasos

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.

Ir a los pasos

Cómo funciona

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 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.
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.
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.
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ó.
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.
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). 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.
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 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

bash · env.sh
# Paste into every terminal you use for this lab. Replace each <PLACEHOLDER> with a throwaway value of your own.
export KC_HOME='<KEYCLOAK_DIR>'          # the unpacked keycloak-26.8.2 folder
export JAVA_HOME='<JDK_DIR>'             # a JDK 21
export KC_URL="http://localhost:8080"
export KC_ADMIN_USER="admin"
export KC_ADMIN_PASSWORD='<ADMIN_PASSWORD>'
export AGENT_A_SECRET='<AGENT_A_SECRET>'
export AGENT_B_SECRET='<AGENT_B_SECRET>'
export AGENT_C_SECRET='<AGENT_C_SECRET>'
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
bash · start-keycloak.sh
export KC_BOOTSTRAP_ADMIN_USERNAME="$KC_ADMIN_USER" KC_BOOTSTRAP_ADMIN_PASSWORD="$KC_ADMIN_PASSWORD"
"$KC_HOME/bin/kc.sh" start-dev --http-port 8080 --features=token-exchange-delegation,parameterized-scopes

Salida esperada

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

Salida esperada

salida
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
python · a2alib.py
import json, os, urllib.error, urllib.parse, urllib.request, uuid
import jwt
from flask import Flask, Response, request

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


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


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


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


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


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


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


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


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


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


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


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


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


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

    @app.post("/message:send")
    def send():
        try:
            return out(reply(handle(request)))
        except Reject as r:
            print(f"AUDIT {name}: DENIED {r.http} {r.reason}", flush=True)
            return out(error_body(r), r.http)
    app.run(port=port)
python · agent_c.py
import os
from a2alib import *

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

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

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

serve("c", PORT, CARD, handle)
python · agent_b.py
import os
from a2alib import *

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

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

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

serve("b", PORT, CARD, handle)
python · agent_a.py
import json, sys
from a2alib import *

B = "http://localhost:19402"
card = fetch_card(B)
skill = card["skills"][0]
want = skill["securityRequirements"][0]["schemes"]["keycloak"]["list"]
flow = card["securitySchemes"]["keycloak"]["oauth2SecurityScheme"]["flows"]["clientCredentials"]
print(f"card says: skill '{skill['id']}' needs scopes {want}, token endpoint {flow['tokenUrl'].split('/realms/')[1]}")
tok = client_credentials("agent-a", " ".join(want))
claims = claims_unverified(tok["access_token"])
print(f"token: aud={claims['aud']} scope='{claims['scope']}' may_act={claims['may_act']['client_id']}")
code, body = send_message(B, tok["access_token"], sys.argv[1] if len(sys.argv) > 1 else "summarize")
print(code, body["message"]["parts"][0]["text"] if code == 200 else json.dumps(body))
bash · start-agents.sh
python3 -m venv .venv && . .venv/bin/activate
pip install -q "PyJWT==2.15.1" "Flask==3.1.3" "cryptography==50.0.2"
nohup python3 agent_c.py > c.log 2>&1 &
nohup python3 agent_b.py > b.log 2>&1 &
sleep 3
curl -s localhost:19403/.well-known/agent-card.json | python3 -c "import sys,json;c=json.load(sys.stdin);print(c['name']);print(list(c['securitySchemes']));print(c['skills'][0]['securityRequirements'])"

Salida esperada

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

Salida esperada

salida
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
python · escal.py
import json, sys
from a2alib import *

scope = sys.argv[1]
KEYS = ("aud", "scope", "azp", "sub", "may_act", "act")
show = lambda t: json.dumps({k: claims_unverified(t)[k] for k in KEYS if k in claims_unverified(t)}, indent=1)
a = client_credentials("agent-a", "agent-b c.read")["access_token"]
b = client_credentials("agent-b")["access_token"]
print("## A's token\n" + show(a))
ex = exchange("agent-b", a, b, "agent-c", scope)
if "access_token" not in ex:
    sys.exit(f"exchange refused: {ex['error']} - {ex['error_description']}")
print("## token B got for C\n" + show(ex["access_token"]))
text = "write: evidence note" if scope == "c.write" else "read"
code, body = send_message("http://localhost:19403", ex["access_token"], text)
print("C says:", body["message"]["parts"][0]["text"] if code == 200 else f"{code} {body['error']['details'][0]['reason']}")
bash · stock-exchange.sh
KCADM="$KC_HOME/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
B_ID=$($KCADM get clients -r a2a -q clientId=agent-b --fields id --format csv --noquotes)
CW_ID=$($KCADM get client-scopes -r a2a --fields id,name --format csv --noquotes | awk -F, '$2=="c.write"{print $1}')
$KCADM get clients/$B_ID/optional-client-scopes -r a2a --fields name --format csv --noquotes | tr '\n' ' '; echo
python3 escal.py c.write

Salida esperada

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

Salida esperada

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

Salida esperada

salida
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
bash · cleanup.sh
pkill -f "agent_[abc].py"
rm -rf "$KC_HOME/data" c.log b.log __pycache__ .venv
unset AGENT_A_SECRET AGENT_B_SECRET AGENT_C_SECRET KC_ADMIN_PASSWORD
pgrep -f "agent_[abc].py" > /dev/null || echo "agents stopped"

Salida esperada

salida
agents stopped

Fuentes#

Comenta este artículo#

¿Te ha servido? Compártelo y dime qué piensas.

Seguir en X

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

Artículos y labs relacionados