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.
Refaire ce lab
J’ai écrit ce lab pour que vous puissiez le refaire vous-même. Chaque étape contient les commandes à copier et la sortie que j’ai obtenue, et vous pouvez la cocher une fois faite. Les coches restent uniquement dans ce navigateur.
Copie un prompt prêt à l’emploi pour Claude Code, Cursor, Codex ou tout autre agent de code. Pour les environnements de test uniquement.
Afficher le 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 avec Keycloak (RFC 8693) : restreindre les jetons pour agents d'IA et serveurs MCP Read the whole lab here (Markdown): https://iamops.dev/fr/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.
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. 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>.
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
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.


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 :
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"
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.

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.
- Le claim
audpeut lister plus que prévu. L’introspection du jeton échangé a montré l’API de paiement etaccount. 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
actpar 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êmeazpdans les journaux.
Enseignements de sécurité#
- L’échange de jetons est un privilège. Accordez-le au seul client qui en a besoin.
- Rendez l’audience en aval explicite et optionnelle, pour que les jetons échangés restent étroits par défaut.
- Ne délivrez jamais de jeton d’actualisation dans un échange. Le serveur du laboratoire les refuse.
- 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.
- 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
# 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" Étapes terminées : 0 sur 6
Étape 1Dé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
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
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 2Cré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
#!/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 Résultat attendu
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 3Obtenir 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
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
--- 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 4L’é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
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
{
"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 5Faire é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
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
# 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 6Nettoyage
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
# 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
000 Sources#
Discuter de cet article#
Utile ? Partagez-le et dites-moi ce que vous en pensez.
Cet article en Markdown · RSS · JSON feed
Les nouveaux articles par e-mail
Un e-mail par semaine avec les nouveaux articles et labs. Désinscription à tout moment.
Votre adresse est conservée chez Kit, le service qui envoie les e-mails. Détails