iamops.dev
Argo sur X Flux RSS
FRFrançais

Labs Technique 5 min de lecture

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.

Deux captures de mon lab Keycloak : la console d'administration avec Standard Token Exchange activé et la sortie du terminal comparant le jeton utilisateur au jeton échangé pour l'API de paiements.
En brefL'échange de jetons RFC 8693 permet à un serveur MCP de remplacer le…
  • 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 6 étapes

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.

Aller aux étapes

Comment ça marche

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

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

bash · env.sh
# 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"
É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
bash · start-keycloak.sh
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

résultat
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
bash · kc-lab.sh
#!/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
chmod +x kc-lab.sh && ./kc-lab.sh

Résultat attendu

résultat
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
bash · user-token.sh
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

résultat
--- 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
bash · exchange.sh
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

résultat
{
  "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
bash · refusals.sh
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

résultat
# 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
bash · cleanup.sh
# 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

résultat
000

Sources#

Discuter de cet article#

Utile ? Partagez-le et dites-moi ce que vous en pensez.

Suivre sur X

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

Articles et labs liés