# OAuth Token Exchange avec Keycloak (RFC 8693) : restreindre les jetons pour agents d'IA et serveurs MCP

> Lab Keycloak : un serveur MCP échange le jeton de l'utilisateur contre un jeton plus restreint pour une API en aval ; trois échanges invalides sont refusés.

- URL: https://iamops.dev/fr/keycloak-token-exchange-rfc-8693/
- Language: fr
- Author: Argo
- Published: 2026-11-12
- Category: Labs
- Topics: Token Exchange, Keycloak, RFC 8693, MCP, Agents d'IA

## En bref

- L'échange de jetons RFC 8693 permet à un serveur MCP de remplacer le jeton de l'utilisateur par un jeton plus restreint, destiné à une seule API en aval.
- Dans Keycloak, il s'active par client, et l'audience en aval est un scope facultatif.
- Le jeton échangé garde l'utilisateur comme sujet, n'a que l'audience en aval, dure 300 secondes et ne contient pas de jeton d'actualisation.
- Trois échanges invalides sont refusés : un client sans le privilège, une audience sans scope et la demande d'un jeton d'actualisation.
- Il n'y a pas de claim act dans cette configuration ; le client agissant n'apparaît que comme authorized party.

Le 12 novembre 2026, Amazon Cognito a ajouté OAuth 2.0 Token Exchange (RFC 8693), quelques jours après WorkOS Connect. Entra propose depuis des années son propre flux on-behalf-of. Le schéma est désormais commun aux grands fournisseurs d'identité : un service qui agit pour un utilisateur échange le jeton de celui-ci contre un nouveau jeton plus restreint, lié à un seul destinataire (audience) et de courte durée, au lieu de transmettre l'original. Je l'ai essayé sur un Keycloak local et j'ai noté ce que faisait le serveur.

Ce laboratoire exécute ce schéma sur un ordinateur portable avec Keycloak, un serveur d'autorisation open source, afin de voir exactement ce qui change dans le jeton et ce que le serveur refuse.

## Ce que montre le laboratoire

Un agent d'IA connecte l'utilisateur et détient un jeton pour un [serveur MCP](https://iamops.dev/fr/mcp-server-no-token-passthrough/). Le serveur MCP doit appeler une API de paiement pour cet utilisateur, sans transmettre le jeton de l'agent. Il le présente donc au serveur d'autorisation et demande un jeton valable uniquement pour l'API de paiement.

Le laboratoire utilise trois clients dans un realm :

| Client | Rôle | Peut échanger des jetons ? |
| --- | --- | --- |
| `agent` | Obtient le jeton de l'utilisateur (password grant, simple raccourci de laboratoire) | Non |
| `mcp-server` | Échange le jeton de l'utilisateur | Oui |
| `payments-api` | Simple audience, l'API en aval | Non |

## Mise en place

Keycloak 26.8.2 a tourné depuis la distribution zip avec Java 21, en mode développement, après une extraction toute neuve. Le mode développement ne sert qu'aux laboratoires. Les mots de passe sont des valeurs jetables ; ils apparaissent ici sous la forme `<lab-password>` et `<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
```

![Sortie du terminal du script de mise en place qui crée le realm agentlab, un utilisateur, trois clients et deux client scopes, avec les identifiants remplacés par des espaces réservés entre chevrons.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/03-setup.webp)

*Mise en place. Le script crée le realm, un utilisateur de test, les trois clients et deux client scopes qui ajoutent des audiences. Les identifiants d'objets sont remplacés par des espaces réservés.*

Dans la console d'administration, deux réglages portent la conception. Seul `mcp-server` a **Standard Token Exchange** activé, et l'audience en aval est un scope *optionnel* : elle n'est ajoutée que si l'échange la demande.

![Console d'administration Keycloak, configuration des capacités du client mcp-server, avec la case Standard Token Exchange cochée.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/05-exchange-toggle.webp)

*Le privilège. Standard Token Exchange n'est coché que sur le client mcp-server. Un client agent compromis ne peut pas émettre de jetons pour d'autres API.*

![Console d'administration Keycloak, client scopes du client mcp-server, avec le scope aud-payments-api indiqué comme Optional.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/06-client-scopes.webp)

*L'audience. aud-payments-api est optionnel pour mcp-server : l'audience en aval doit donc être demandée explicitement.*

## Le déroulement

L'agent obtient un jeton utilisateur, puis le serveur MCP l'échange. La requête centrale est un unique appel au point de terminaison des jetons :

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

![Sortie du terminal comparant le jeton utilisateur décodé et le jeton échangé. L'audience passe de mcp-server et account à payments-api, azp passe de agent à mcp-server, expires_in vaut 300, sans jeton d'actualisation ni claim act.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/07-exchange.webp)

*Avant et après. Même utilisateur, nouvelle audience (payments-api), nouvelle partie autorisée (mcp-server), 300 secondes de validité, pas de jeton d'actualisation. L'identifiant de l'utilisateur est remplacé par un espace réservé.*

Comparez les deux jetons : le sujet est inchangé, l'audience est désormais uniquement l'API de paiement, la partie autorisée (`azp`) désigne le serveur MCP, la durée de vie est de 300 secondes et aucun jeton d'actualisation n'est renvoyé. Il n'y a **pas de claim `act`** : la prise en charge de la délégation par Keycloak est une fonction en préversion, désactivée par défaut ; l'acteur n'apparaît donc que sous la forme `azp`.

## Faire échouer exprès

Trois échanges doivent être refusés. Testez les trois mêmes cas chez n'importe quel fournisseur d'identité avant de lui confier la délégation pour des agents.

![Sortie du terminal de trois échanges refusés : un client sans token exchange activé, une audience pour laquelle le serveur MCP n'a pas de scope, et la demande d'un jeton d'actualisation ; chacun renvoie invalid_request.](https://iamops.dev/media/keycloak-token-exchange-rfc-8693/08-negative.webp)

*Trois refus. A : un client sans le privilège d'échange. B : une audience pour laquelle le serveur MCP n'a pas de scope. C : un jeton d'actualisation. Tous renvoient invalid_request. Les secrets de client sont remplacés par des espaces réservés.*

## Pièges

- **Le password grant est un raccourci.** Le laboratoire ne l'utilise que pour obtenir vite un jeton utilisateur. La RFC 9700 et OAuth 2.1 l'écartent pour les vrais clients ; utilisez le flux authorization code avec [PKCE](https://iamops.dev/fr/tools/pkce/).
- **Le claim `aud` peut lister plus que prévu.** L'introspection du jeton échangé a montré l'API de paiement et `account`. Comprenez-le avant de vous reposer sur des contrôles d'audience.
- **L'ordre des scopes varie** d'une exécution à l'autre ; ne comparez donc pas les chaînes de scopes à la lettre.
- **Pas de claim `act` par défaut.** Si votre audit a besoin de l'acteur, prévoyez la fonction de délégation en préversion ou reliez vous-même `azp` dans les journaux.

## Enseignements de sécurité

1. L'échange de jetons est un privilège. Accordez-le au seul client qui en a besoin.
2. Rendez l'audience en aval explicite et optionnelle, pour que les jetons échangés restent étroits par défaut.
3. Ne délivrez jamais de jeton d'actualisation dans un échange. Le serveur du laboratoire les refuse.
4. Un service doit rejeter les jetons qui ne lui sont pas destinés et échanger pour chaque API en aval, sans jamais transmettre le jeton de l'utilisateur.
5. Vérifiez ce que votre piste d'audit peut reconstituer. Si l'acteur n'apparaît que sous `azp`, une ligne de journal doit relier utilisateur, agent et audience en aval.

## Ce qui n'a pas été exécuté

La variante Docker, les exercices complémentaires (jetons d'actualisation dans l'échange standard, introspection par l'API en aval) et la fonction de délégation en préversion qui ajouterait `act` n'ont pas été exécutés. Le laboratoire n'a utilisé que des comptes jetables. Aucun enregistrement n'est publié pour ce laboratoire.

*Les images du terminal ont été générées à partir de la sortie enregistrée de l'exécution, avec identifiants et secrets remplacés par des espaces réservés. Les captures de la console Keycloak ne montrent que des objets de test.*

## Refaire ce lab

Tout ce qu’il faut pour exécuter ce lab sur un portable en une quarantaine de minutes : un Keycloak local, un script qui crée le realm, un qui réalise l’échange et trois qui doivent échouer. Ouvrez chaque étape, copiez les blocs et comparez votre résultat avec celui attendu.

Chaque valeur entre chevrons est un espace réservé pour votre environnement de test. Rien sur cette page n’est un identifiant ou un secret réel.

**Définissez vos variables une seule fois** `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"
```

### Étape 1: Démarrer Keycloak en mode développement

**Objectif.** Lancez un serveur d’autorisation local que vous maîtrisez, pour voir ce que l’échange de jetons change dans un jeton.

**Prérequis**

- Java 21 (par exemple Eclipse Temurin), curl, jq et unzip
- Port 8080 libre ; gardez ce terminal ouvert et utilisez-en un second pour les étapes suivantes

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

**Résultat attendu**

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

### Étape 2: Créer le realm, l’utilisateur et trois clients

**Objectif.** Construisez le realm agentlab avec l’utilisateur alice et trois clients : agent reçoit le jeton de l’utilisateur, mcp-server peut l’échanger, payments-api n’est qu’une audience.

**Prérequis**

- Étape 1 terminée et Keycloak en marche ; les variables du début de cette section définies dans ce second terminal
- À exécuter depuis le dossier qui contient le répertoire 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
```

**Résultat attendu**

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

### Étape 3: Obtenir le jeton de l’utilisateur en tant qu’agent

**Objectif.** Obtenez le jeton que recevra le serveur MCP et décodez-le, pour avoir une base de comparaison avec le jeton échangé.

**Prérequis**

- Étape 2 terminée (le realm agentlab existe)
- Le password grant n’est qu’un raccourci de lab ; les vrais clients utilisent le flux authorization code avec 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}'
```

**Résultat attendu**

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

### Étape 4: L’échanger en tant que serveur MCP (RFC 8693)

**Objectif.** Échangez le jeton de l’utilisateur contre un jeton plus étroit, destiné uniquement à l’API de paiements, et vérifiez ce qui a changé.

**Prérequis**

- Étape 3 terminée dans le même terminal, afin que USER_AT soit défini

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

**Résultat attendu**

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

### Étape 5: Faire échouer trois échanges exprès

**Objectif.** Vérifiez les trois refus qui empêchent un maillon compromis d’élargir sa portée : pas de privilège, pas de scope d’audience, pas de refresh token.

**Prérequis**

- Étape 3 terminée dans le même terminal, afin que USER_AT soit défini
- Les jetons vivent cinq minutes ; en cas d’erreur de jeton, refaites d’abord l’étape 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 .
```

**Résultat attendu**

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

### Étape 6: Nettoyage

**Objectif.** Arrêtez Keycloak et supprimez tout ce que le lab a créé, y compris la distribution téléchargée et le fichier du jeton échangé.

**Prérequis**

- Rien d’autre n’utilise le port 8080 ni le répertoire 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/"
```

**Résultat attendu**

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