# OAuth Token Exchange con Keycloak (RFC 8693): restringir tokens para agentes de IA y servidores MCP

> Laboratorio con Keycloak: un servidor MCP cambia el token del usuario por otro más estrecho para una API posterior y se rechazan tres intercambios no válidos.

- URL: https://iamops.dev/es/keycloak-token-exchange-rfc-8693/
- Language: es
- Author: Argo
- Published: 2026-11-12
- Category: Labs
- Topics: Intercambio de tokens, Keycloak, RFC 8693, MCP, Agentes de IA

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

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](https://iamops.dev/es/mcp-server-no-token-passthrough/). 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>`.

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

![Salida de terminal del script de preparación que crea el realm agentlab, un usuario, tres clientes y dos client scopes, con los identificadores sustituidos por marcadores entre corchetes angulares.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/03-setup.webp)

*Preparación. El script crea el realm, un usuario de prueba, los tres clientes y dos client scopes que añaden audiencias. Los ID de los objetos están sustituidos por marcadores.*

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.

![Consola de administración de Keycloak, configuración de capacidades del cliente mcp-server, con la casilla Standard Token Exchange marcada.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/05-exchange-toggle.webp)

*El privilegio. Standard Token Exchange está marcado solo en el cliente mcp-server. Un cliente agente comprometido no puede emitir tokens para otras API.*

![Consola de administración de Keycloak, client scopes del cliente mcp-server, con el scope aud-payments-api indicado como Optional.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/06-client-scopes.webp)

*La audiencia. aud-payments-api es opcional para mcp-server, así que la audiencia posterior debe pedirse de forma explícita.*

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

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

![Salida de terminal que compara el token de usuario decodificado con el token intercambiado. La audiencia pasa de mcp-server y account a payments-api, azp pasa de agent a mcp-server, expires_in es 300 y no hay token de refresco ni claim act.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/07-exchange.webp)

*Antes y después. Mismo usuario, nueva audiencia (payments-api), nueva parte autorizada (mcp-server), 300 segundos de vida y ningún token de refresco. El identificador del usuario está sustituido por un marcador.*

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.

![Salida de terminal de tres intercambios rechazados: un cliente sin token exchange activado, una audiencia para la que el servidor MCP no tiene scope y la petición de un token de refresco; cada uno devuelve invalid_request.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/08-negative.webp)

*Tres rechazos. A: un cliente sin el privilegio de intercambio. B: una audiencia para la que el servidor MCP no tiene scope. C: un token de refresco. Todos devuelven invalid_request. Los secretos de cliente están sustituidos por marcadores.*

## 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](https://iamops.dev/es/tools/pkce/).
- **El claim `aud` puede listar más de lo esperado.** Al introspeccionar el token intercambiado aparecieron la API de pagos y `account`. 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 `act` por defecto.** Si su auditoría necesita al actor, prevea la función de delegación en vista previa o una los datos usted mismo mediante `azp` en los registros.

## Conclusiones de seguridad

1. El intercambio de tokens es un privilegio. Concédalo solo al cliente que lo necesita.
2. Haga la audiencia posterior explícita y opcional, para que los tokens intercambiados sean estrechos por defecto.
3. No emita nunca tokens de refresco en un intercambio. El servidor del laboratorio los rechaza.
4. 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.
5. 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** `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_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="alice@example.com"
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"
```

### Paso 1: Inicia 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

`start-keycloak.sh` (bash)

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

```text
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 2: Crea 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

`kc-lab.sh` (bash)

```bash
#!/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"
```

(bash)

```bash
chmod +x kc-lab.sh && ./kc-lab.sh
```

**Salida esperada**

```text
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 3: Obté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

`user-token.sh` (bash)

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

```json
--- 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 4: Intercá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

`exchange.sh` (bash)

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

```json
{
  "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 5: Haz 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

`refusals.sh` (bash)

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

```text
# 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 6: Limpieza

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

`cleanup.sh` (bash)

```bash
# 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**

```text
000
```


## Sources

- [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)
- [AWS What's New, 12 Nov 2026: Amazon Cognito now supports OAuth 2.0 token exchange](https://aws.amazon.com/about-aws/whats-new/2026/11/cognito-token-exchange/)
- [WorkOS changelog: Token exchange for WorkOS Connect](https://workos.com/changelog/token-exchange-for-workos-connect)
- [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://www.rfc-editor.org/rfc/rfc9700)
