En resumen
- El intercambio de tokens RFC 8693 permite a un servidor MCP cambiar el token del usuario por otro más estrecho, dirigido a una sola API posterior.
- En Keycloak se activa por cliente, y la audiencia posterior es un scope opcional.
- El token intercambiado mantiene al usuario como sujeto, tiene solo la audiencia posterior, dura 300 segundos y no incluye refresh token.
- Se rechazan tres intercambios no válidos: un cliente sin el privilegio, una audiencia sin scope y la petición de un refresh token.
- En esta configuración no hay claim act, así que el cliente que actúa aparece solo como authorized party.
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: OAuth Token Exchange con Keycloak (RFC 8693): restringir tokens para agentes de IA y servidores MCP Read the whole lab here (Markdown): https://iamops.dev/es/keycloak-token-exchange-rfc-8693.md What the lab needs before the first step: - Java 21 (for example Eclipse Temurin), curl, jq and unzip - 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): <ADMIN_PASSWORD>, <ALICE_PASSWORD>, <AGENT_CLIENT_SECRET>, <MCP_SERVER_CLIENT_SECRET>, <PAYMENTS_API_CLIENT_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.
El 12 de noviembre de 2026 Amazon Cognito añadió OAuth 2.0 Token Exchange (RFC 8693), pocos días después que WorkOS Connect. Entra lleva años con su propio flujo on-behalf-of. El patrón ya es común a los grandes proveedores de identidad: un servicio que actúa por un usuario intercambia el token de este por un token nuevo, más restringido, ligado a un solo destinatario (audiencia) y de corta duración, en lugar de reenviar el original. Lo probé contra un Keycloak local y anoté qué hizo el servidor.
Este laboratorio ejecuta el patrón en un portátil con Keycloak, un servidor de autorización de código abierto, para ver exactamente qué cambia dentro del token y qué rechaza el servidor.
Qué muestra el laboratorio#
Un agente de IA inicia sesión al usuario y recibe un token para un servidor MCP. El servidor MCP debe llamar a una API de pagos por ese usuario, pero no debe reenviar el token del agente. En su lugar lo presenta al servidor de autorización y pide un token válido solo para la API de pagos.
El laboratorio usa tres clientes en un realm:
| Cliente | Función | ¿Puede intercambiar tokens? |
|---|---|---|
agent |
Obtiene el token del usuario (password grant, solo atajo de laboratorio) | No |
mcp-server |
Intercambia el token del usuario | Sí |
payments-api |
Solo una audiencia, la API posterior | No |
Preparación#
Keycloak 26.8.2 se ejecutó desde la distribución zip con Java 21, en modo desarrollo y tras descomprimir de cero. El modo desarrollo es solo para laboratorios. Las contraseñas son valores desechables; en este artículo aparecen como <lab-password> y <client-secret>.
export KC_BOOTSTRAP_ADMIN_USERNAME=admin KC_BOOTSTRAP_ADMIN_PASSWORD=<lab-password>
keycloak-26.8.2/bin/kc.sh start-dev --http-port 8080
./kc-lab.sh # creates realm agentlab, user alice, the three clients and two audience scopes
En la consola de administración dos ajustes sostienen el diseño. Solo mcp-server tiene activado Standard Token Exchange, y la audiencia posterior es un scope opcional, de modo que solo se añade cuando el intercambio la pide.


La ejecución#
El agente obtiene un token de usuario y luego el servidor MCP lo intercambia. La petición central es una sola llamada al endpoint de tokens:
curl -s -u mcp-server:<client-secret> \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$USER_AT" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
-d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL"
Compare los dos tokens: el sujeto no cambia, la audiencia es ahora solo la API de pagos, la parte autorizada (azp) nombra al servidor MCP, la vida es de 300 segundos y no vuelve ningún token de refresco. No hay claim act: el soporte de delegación de Keycloak es una función en vista previa y está desactivada por defecto, por lo que el actor solo aparece como azp.
Hacerlo fallar a propósito#
Tres intercambios deben rechazarse. Pruebe esos mismos tres en cualquier proveedor de identidad antes de confiarle la delegación para agentes.

Trampas habituales#
- El password grant es un atajo. El laboratorio solo lo usa para conseguir rápido un token de usuario. RFC 9700 y OAuth 2.1 lo descartan para clientes reales; use el flujo authorization code con PKCE.
- El claim
audpuede listar más de lo esperado. Al introspeccionar el token intercambiado aparecieron la API de pagos yaccount. Entiéndalo antes de confiar en las comprobaciones de audiencia. - El orden de los scopes varía entre ejecuciones, así que no compare cadenas de scopes literalmente.
- Sin claim
actpor defecto. Si su auditoría necesita al actor, prevea la función de delegación en vista previa o una los datos usted mismo medianteazpen los registros.
Conclusiones de seguridad#
- El intercambio de tokens es un privilegio. Concédalo solo al cliente que lo necesita.
- Haga la audiencia posterior explícita y opcional, para que los tokens intercambiados sean estrechos por defecto.
- No emita nunca tokens de refresco en un intercambio. El servidor del laboratorio los rechaza.
- Un servicio debe rechazar los tokens que no se emitieron para él e intercambiar por cada API posterior, sin reenviar nunca el token del usuario.
- Compruebe qué puede reconstruir su rastro de auditoría. Si el actor solo aparece como
azp, una línea de registro debe unir usuario, agente y audiencia posterior.
Qué no se ejecutó#
No se ejecutaron la variante con Docker, las tareas adicionales (tokens de refresco en el intercambio estándar, introspección por la API posterior) ni la función de delegación en vista previa que añadiría act. El laboratorio usó solo cuentas desechables. Para este laboratorio no se publica ninguna grabación.
Las imágenes del terminal se generaron a partir de la salida guardada de la ejecución, con identificadores y secretos sustituidos por marcadores. Las capturas de la consola de Keycloak muestran solo objetos de prueba.
Repite este lab#
Todo lo necesario para ejecutar este lab en un portátil en unos 45 minutos: un Keycloak local, un script que crea el realm, otro que hace el intercambio y tres que deben fallar. 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_VERSION="26.8.2"
export KC_URL="http://localhost:8080"
export KC_REALM="agentlab"
export KC_ADMIN_USER="admin"
export KC_ADMIN_PASSWORD='<ADMIN_PASSWORD>'
export ALICE_EMAIL="[email protected]"
export ALICE_PASSWORD='<ALICE_PASSWORD>'
export AGENT_SECRET='<AGENT_CLIENT_SECRET>'
export MCP_SECRET='<MCP_SERVER_CLIENT_SECRET>'
export PAYMENTS_SECRET='<PAYMENTS_API_CLIENT_SECRET>'
export TOKEN_URL="$KC_URL/realms/$KC_REALM/protocol/openid-connect/token" 0 de 6 pasos hechos
Paso 1Inicia Keycloak en modo desarrollo
Objetivo. Ejecuta un servidor de autorización local que controles por completo, para ver qué cambia el intercambio de tokens dentro de un token.
Requisitos
- Java 21 (por ejemplo Eclipse Temurin), curl, jq y unzip
- Puerto 8080 libre; deja abierta esta terminal y usa una segunda para los pasos siguientes
curl -LO "https://github.com/keycloak/keycloak/releases/download/$KC_VERSION/keycloak-$KC_VERSION.zip"
unzip -q "keycloak-$KC_VERSION.zip"
export KC_BOOTSTRAP_ADMIN_USERNAME="$KC_ADMIN_USER" KC_BOOTSTRAP_ADMIN_PASSWORD="$KC_ADMIN_PASSWORD"
"keycloak-$KC_VERSION/bin/kc.sh" start-dev --http-port 8080 Salida esperada
Running the server in development mode. DO NOT use this configuration in production.
INFO [org.keycloak.services] (main) KC-SERVICES0077: Created temporary admin user with username admin
INFO [io.quarkus] (main) Keycloak 26.8.2 on JVM (powered by Quarkus 3.40.1.1) started in 8.418s. Listening on: http://localhost:8080
INFO [io.quarkus] (main) Profile dev activated. Paso 2Crea el realm, el usuario y tres clientes
Objetivo. Construye el realm agentlab con el usuario alice y tres clientes: agent recibe el token del usuario, mcp-server puede intercambiarlo y payments-api es solo una audiencia.
Requisitos
- Paso 1 terminado y Keycloak en marcha; las variables del inicio de esta sección definidas en esta segunda terminal
- Ejecuta desde la carpeta que contiene el directorio keycloak
#!/usr/bin/env bash
# Realm, user, three clients and two audience scopes. Lab only: throwaway secrets.
set -euo pipefail
KCADM="keycloak-$KC_VERSION/bin/kcadm.sh"
$KCADM config credentials --server "$KC_URL" --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASSWORD"
$KCADM create realms -s realm="$KC_REALM" -s enabled=true
$KCADM create users -r "$KC_REALM" -s username=alice -s enabled=true -s email="$ALICE_EMAIL" -s emailVerified=true -s firstName=Alice -s lastName=Lab
$KCADM set-password -r "$KC_REALM" --username alice --new-password "$ALICE_PASSWORD"
# Downstream API: only an audience
$KCADM create clients -r "$KC_REALM" -s clientId=payments-api -s publicClient=false -s secret="$PAYMENTS_SECRET" -s standardFlowEnabled=false -s directAccessGrantsEnabled=false
# MCP server: confidential, allowed to exchange tokens
$KCADM create clients -r "$KC_REALM" -s clientId=mcp-server -s publicClient=false -s secret="$MCP_SECRET" -s standardFlowEnabled=false -s directAccessGrantsEnabled=false -s 'attributes."standard.token.exchange.enabled"=true'
# Agent: gets the user token (password grant only because this is a lab)
$KCADM create clients -r "$KC_REALM" -s clientId=agent -s publicClient=false -s secret="$AGENT_SECRET" -s directAccessGrantsEnabled=true -s standardFlowEnabled=true -s 'redirectUris=["http://localhost:6274/*"]'
# Client scopes that add audiences
for AUD in mcp-server payments-api; do
SID=$($KCADM create client-scopes -r "$KC_REALM" -s name=aud-$AUD -s protocol=openid-connect -s 'attributes."include.in.token.scope"=true' -i)
$KCADM create client-scopes/$SID/protocol-mappers/models -r "$KC_REALM" -s name=aud-$AUD -s protocol=openid-connect -s protocolMapper=oidc-audience-mapper -s "config.\"included.client.audience\"=$AUD" -s 'config."access.token.claim"=true'
done
AGENT=$($KCADM get clients -r "$KC_REALM" -q clientId=agent --fields id --format csv --noquotes)
MCP=$($KCADM get clients -r "$KC_REALM" -q clientId=mcp-server --fields id --format csv --noquotes)
S1=$($KCADM get client-scopes -r "$KC_REALM" --fields id,name --format csv --noquotes | awk -F, '$2=="aud-mcp-server"{print $1}')
S2=$($KCADM get client-scopes -r "$KC_REALM" --fields id,name --format csv --noquotes | awk -F, '$2=="aud-payments-api"{print $1}')
# agent always gets the mcp-server audience; mcp-server may ask for payments-api as an optional scope
$KCADM update clients/$AGENT/default-client-scopes/$S1 -r "$KC_REALM"
$KCADM update clients/$MCP/optional-client-scopes/$S2 -r "$KC_REALM"
echo "realm $KC_REALM ready" chmod +x kc-lab.sh && ./kc-lab.sh Salida esperada
Logging into http://localhost:8080 as user admin of realm master
Created new realm with id 'agentlab'
Created new user with id '<user-id>'
Created new client with id '<client-id>'
Created new client with id '<client-id>'
Created new client with id '<client-id>'
Created new model with id '<scope-id>'
Created new model with id '<scope-id>'
realm agentlab ready Paso 3Obtén el token del usuario como agent
Objetivo. Obtén el token que recibirá el servidor MCP y decodifícalo, para tener una referencia con la que comparar el token intercambiado.
Requisitos
- Paso 2 terminado (el realm agentlab existe)
- El password grant es solo un atajo de laboratorio; los clientes reales usan el flujo authorization code con PKCE
jwtp() { cut -d. -f2 | tr '_-' '/+' | awk '{l=length($0)%4; if(l==2)$0=$0"=="; else if(l==3)$0=$0"="; print}' | base64 -d 2>/dev/null; }
USER_AT=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
-d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
echo "--- user token seen by mcp-server"
echo "$USER_AT" | jwtp | jq '{iss,aud,azp,sub,preferred_username,scope}' Salida esperada
--- user token seen by mcp-server
{
"iss": "http://localhost:8080/realms/agentlab",
"aud": ["mcp-server", "account"],
"azp": "agent",
"sub": "<user-id>",
"preferred_username": "alice",
"scope": "openid profile aud-mcp-server email"
} Paso 4Intercámbialo como servidor MCP (RFC 8693)
Objetivo. Cambia el token del usuario por uno más estrecho, dirigido solo a la API de pagos, y comprueba qué ha cambiado.
Requisitos
- Paso 3 terminado en la misma terminal, de modo que USER_AT esté definido
curl -s -u "mcp-server:$MCP_SECRET" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token="$USER_AT" \
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
-d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
-d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL" > exch.json
jq '{issued_token_type,token_type,expires_in,scope, refresh: (has("refresh_token"))}' exch.json
echo "--- exchanged token for payments-api"
jq -r .access_token exch.json | jwtp | jq '{iss,aud,azp,sub,preferred_username,scope,act}' Salida esperada
{
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 300,
"scope": "aud-payments-api profile email",
"refresh": false
}
--- exchanged token for payments-api
{
"iss": "http://localhost:8080/realms/agentlab",
"aud": "payments-api",
"azp": "mcp-server",
"sub": "<user-id>",
"preferred_username": "alice",
"scope": "aud-payments-api profile email",
"act": null
} Paso 5Haz fallar tres intercambios a propósito
Objetivo. Comprueba los tres rechazos que impiden que un eslabón comprometido amplíe su alcance: sin privilegio, sin scope de audiencia y sin refresh token.
Requisitos
- Paso 3 terminado en la misma terminal, de modo que USER_AT esté definido
- Los tokens duran cinco minutos; si recibes un error de token, repite antes el paso 3
X=(-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token="$USER_AT"
-d subject_token_type=urn:ietf:params:oauth:token-type:access_token)
echo "# A: a client without token exchange enabled"
curl -s -u "payments-api:$PAYMENTS_SECRET" "${X[@]}" -d audience=mcp-server "$TOKEN_URL" | jq .
echo "# B: an audience mcp-server has no scope for"
curl -s -u "mcp-server:$MCP_SECRET" "${X[@]}" -d audience=agent "$TOKEN_URL" | jq .
echo "# C: ask for a refresh token"
curl -s -u "mcp-server:$MCP_SECRET" "${X[@]}" -d audience=payments-api -d scope=aud-payments-api \
-d requested_token_type=urn:ietf:params:oauth:token-type:refresh_token "$TOKEN_URL" | jq . Salida esperada
# A: a client without token exchange enabled
{
"error": "invalid_request",
"error_description": "Standard token exchange is not enabled for the requested client"
}
# B: an audience mcp-server has no scope for
{
"error": "invalid_request",
"error_description": "Requested audience not available: agent"
}
# C: ask for a refresh token
{
"error": "invalid_request",
"error_description": "requested_token_type unsupported"
} Paso 6Limpieza
Objetivo. Detén Keycloak y borra todo lo que creó el lab, incluida la distribución descargada y el archivo del token intercambiado.
Requisitos
- Nada más usa el puerto 8080 ni el directorio keycloak
# Stop Keycloak: press Ctrl+C in the first terminal, or:
pkill -f "keycloak-$KC_VERSION" || true
rm -rf "keycloak-$KC_VERSION" "keycloak-$KC_VERSION.zip" kc-lab.sh exch.json
unset KC_ADMIN_PASSWORD ALICE_PASSWORD AGENT_SECRET MCP_SECRET PAYMENTS_SECRET USER_AT
# check: nothing listens on port 8080 any more
curl -s -o /dev/null -w "%{http_code}\n" "$KC_URL/" Salida esperada
000 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