Repères du module · Repère rapide
Votre objectif dans ce module (20 min)
Rejouez les appels aux outils du laboratoire et la sonde de disponibilité après le chargement d’une politique signée.
Voir le détail vérifié
Repères M2 : passerelle réelle, fournisseur CP de labo et origine des captures
Ce second module reprend le cas Hélios et passe de l’accès à une route REST à l’exécution d’outils MCP.
STOA Gateway (639e8b9a) et Keycloak (26.5.3) sont réels ; dans Compose, tout le service control-plane est remplacé par un fournisseur CP de labo annoncé (policy_fixture.py : signature JWS, /health et trois réponses minimales de découverte).
Les réponses affichées proviennent de captures Python urllib du statut HTTP et du corps. Les commandes curl -w sont les équivalents de reproduction. La liste de 17 outils est présentée sous forme d’extrait filtré.
Le cas · entreprise fictive
Hélios Distribution ouvre un outil MCP de lecture et bloque une action sensible
Hélios Distribution ouvre un outil de consultation à un agent IA tout en interdisant fermement une action sensible.
Voir le détail vérifié
Après sa route REST du module 1, Hélios Distribution veut autoriser l’outil MCP ping-api-0, bloquer ping-api-1 et brancher un orchestrateur sur GET /health/ready.
Au commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913, stoa-gateway attend un JWS Ed25519 sur GET /v1/tenants/quickstart/tool-permissions/artifact, et cette requête a renvoyé HTTP 405 Method Not Allowed lors de l’essai avec l’image control-plane-api:1.14.1 épinglée.
Sans toucher à stoa-gateway ni Keycloak (réels), l’équipe remplace le service control-plane dans Compose par un fournisseur CP de laboratoire annoncé (policy_fixture.py : signature JWS, /health et réponses minimales de découverte), sans qualifier le Control Plane produit.
Autour de la table, chacun pose la question de son métier.
- Claire, DSI Si /health/ready passe à 200 et que l’agent voit l’outil listé, qu’est-ce qui prouve le blocage et quelle réserve impose le fournisseur CP de labo ?
- Mehdi, chef de projet API Quels critères d’acceptation écrire pour /health/ready, POST /mcp/tools/list et les deux routes d’appel (/mcp/tools/call et JSON-RPC /mcp) ?
- Nadia, architecte sécurité Comment stoa-gateway s’authentifie-t-elle via private_key_jwt (RSA) puis vérifie-t-elle le JWS Ed25519 via le JWKS épinglé, que contrôle /health/ready et pourquoi JSON-RPC répond-il sous HTTP 200 ?
- Lucas, ingénieur plateforme Quelles variables STOA_POLICY_*, payloads et script isolé (tools/run-lab-m2.sh) reproduisent 503 -> 200, les 17 outils et les refus 403 / -32001 ?
Entreprise fictive. Le cas illustre une situation réelle d’exposition d’API ; seules les réponses enregistrées lors des essais vérifiés sur les bancs locaux STOA servent de preuve (statuts et corps capturés sans retouche).
Votre avis
« Dès que GET /health/ready renvoie HTTP 200 READY et qu’un outil figure dans POST /mcp/tools/list, son exécution est autorisée. »
Voir ce que montre l’essai
Sur le banc vérifié, GET /health/ready répond 200 READY et POST /mcp/tools/list inclut uac:quickstart:ping-api:ping-api-1, mais son appel échoue en HTTP 403 (/mcp/tools/call) et en code JSON-RPC -32001 sous HTTP 200 (/mcp).
Leçon 1
Image Control Plane épinglée (405), politique Ed25519 et bascule /health/ready de 503 à 200
Traces réelles capturées le 15 novembre 2026
Claire, DSI Pourquoi remplacer control-plane par un fournisseur de labo dans Compose, et qu’atteste /health/ready en 200 ?
Mehdi, chef de projet API Quel prérequis sépare le 503 du module 1 d’une sonde /health/ready en 200 exploitable ?
Nadia, architecte sécurité Comment stoa-gateway, Keycloak et le fournisseur JWS Ed25519 interagissent-ils au démarrage ?
Lucas, ingénieur plateforme Que répond control-plane-api:1.14.1 sur /tool-permissions/artifact, et comment réagit /health/ready entre signature altérée et valide ?
Au module 1, GET /health/ready restait en 503 sans politique chargée. Avec STOA_POLICY_BOOT_TENANTS=quickstart (commit 639e8b9a), stoa-gateway s’authentifie auprès de Keycloak en private_key_jwt (assertion RSA) pour obtenir un jeton d’accès, appelle GET /v1/tenants/quickstart/tool-permissions/artifact et vérifie le JWS Ed25519 via le JWKS épinglé. Examinons control-plane-api:1.14.1 puis le banc de labo.
- STOA Gateway s’authentifie sur Keycloak en private_key_jwt (RSA), reçoit un jeton d’accès et vérifie le JWS Ed25519 via le JWKS épinglé : signature altérée -> /health/ready 503, valide -> 200 READY.
- La politique étant chargée, l’opérateur publie sur POST /admin/contracts le contrat ping-api (/ping et /blocked pointant vers backend_url http://backend:80).
- Avec le jeton quickstart-caller, POST /mcp/tools/list renvoie HTTP 200 avec 17 outils, dont ping-api-0 et ping-api-1.
- Dans les traces, les appels avec le JWT du locataire quickstart sont soumis à la politique signée, sur /mcp/tools/call et /mcp.
- Seul ping-api-0 (allowed: true) appelle la racine http://backend:80 ; ping-api-1 (allowed: false) est bloqué en amont.
Cliquez sur un élément du schéma pour voir son rôle.
- fournisseur CP labo JWS Ed25519
- Service control-plane remplacé dans Compose par policy_fixture.py (:8890) : signature JWS, /health et trois réponses minimales de découverte.
- Client MCP Admin & appels
- Publie le contrat (/ping et /blocked), interroge /mcp/tools/list puis appelle ping-api-0 et ping-api-1 en HTTP simple et JSON-RPC.
- keycloak Realm & service
- Keycloak 26.5.3 réel : authentifie la passerelle en private_key_jwt (assertion RSA) avant d’émettre son jeton d’accès, et délivre le jeton client_credentials de quickstart-caller.
- gateway Rust 0.9.25
- STOA Gateway réelle : vérifie le JWS Ed25519 via le JWKS épinglé, contrôle santé CP/OIDC + politique sur /health/ready (200) et filtre chaque appel.
- backend nginx 1.27.5
- Cible backend_url http://backend:80 : appelée à sa racine par ping-api-0 (autorisé), jamais atteinte par ping-api-1 (refusé).
À vous de prédire
Sur la pile quickstart d’origine, que répond control-plane-api:1.14.1 sur GET /v1/tenants/quickstart/tool-permissions/artifact ?
Révéler la réponse enregistrée
Fait mesuré sur l’image control-plane-api:1.14.1 épinglée : la route d’artefact signé renvoie HTTP 405.
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 405
{"detail":"Method Not Allowed"}Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8890/v1/tenants/quickstart/tool-permissions/artifact"Remise en ordre
Ordonnez les quatre étapes qui passent GET /health/ready de 503 à 200 sur le banc vérifié :
Voir l’ordre vérifié
- Démarrer stoa-gateway avec STOA_POLICY_BOOT_TENANTS=quickstart, le JWKS épinglé Ed25519 (STOA_POLICY_TRUST_JWKS_FILE) et sa clé RSA d’authentification client private_key_jwt. La passerelle connaît ainsi le boot tenant, l’ancre Ed25519 et son identité OIDC.
- Servir un JWS à signature altérée sur le fournisseur CP de labo : stoa-gateway rejette la signature et garde /health/ready en 503. Ce test négatif sur readiness prouve le contrôle cryptographique Ed25519.
- Activer une signature Ed25519 valide sur le fournisseur CP (typ: stoa-tool-policy+jws, ping-api-0 autorisé, ping-api-1 refusé). La synchronisation charge alors la politique signée du locataire quickstart.
- Interroger GET /health/ready et observer HTTP 200 READY (santé CP/OIDC valide et politique disponible). Le handler vérifie santé CP/OIDC configurée et disponibilité de la politique.
À vous de prédire
Une fois le JWS Ed25519 valide chargé (et CP/OIDC sains), que renvoie GET /health/ready ?
Révéler la réponse enregistrée
Bascule vérifiée sur STOA Gateway : GET /health/ready passe à HTTP 200 READY.
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200
READYVoir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8892/health/ready"La règle Sur STOA Gateway (639e8b9a), GET /health/ready contrôle la santé CP/OIDC configurée et l’état des politiques : son passage à 200 READY atteste notamment un JWS Ed25519 valide chargé, servi ici par un fournisseur CP de labo après le 405 observé avec l’image control-plane-api:1.14.1 épinglée.
Détail Expert : signature altérée au premier octet (XOR 1) et structure JWS
Dans policy_fixture.py, le mode initial altère la signature brute Ed25519 au premier octet (signature[0] ^ 1) ; ce cas a été testé par /health/ready (HTTP 503 NOT READY: tool policy unavailable). Le JWS valide porte alg: EdDSA, typ: stoa-tool-policy+jws, kid: cp-policy-202611-1, iss: stoa-control-plane, aud: stoa-gateway et tenant_id: quickstart.
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 503
NOT READY: tool policy unavailableVoir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X GET "http://127.0.0.1:8892/health/ready"Vérifiez vos acquis
Choisissez une réponse : la correction s’affiche aussitôt.
Quel est le rôle exact de policy_fixture.py dans le montage Compose du module 2 ?
Suppléer un vérificateur Ed25519 absent de STOA Gateway.
Pas tout à fait. Faux : STOA Gateway vérifie elle-même la signature Ed25519.
Remplacer le service control-plane complet dans Compose comme fournisseur CP de laboratoire (signature JWS après le 405 observé sur l’image épinglée, /health et réponses minimales de découverte), sans qualifier le Control Plane produit.
Bonne réponse. Exact : tout le service control-plane est remplacé dans Compose, pas une route isolée.
Remplacer Keycloak 26.5.3 pour émettre les jetons OIDC.
Pas tout à fait. Faux : Keycloak 26.5.3 est réel et non modifié.
Leçon 2
Contrat à deux endpoints, découverte POST /mcp/tools/list et présence de l’outil interdit
Traces réelles capturées le 15 novembre 2026
Claire, DSI Pourquoi la présence d’un outil dans la liste retournée à un agent IA ne prouve-t-elle jamais le droit de l’exécuter ?
Mehdi, chef de projet API Comment tester POST /admin/contracts et POST /mcp/tools/list sans confondre découverte et autorisation ?
Nadia, architecte sécurité Comment stoa-gateway nomme-t-elle les outils UAC et quels attributs porte le jeton lecteur ?
Lucas, ingénieur plateforme Quels outils sont créés pour /ping et /blocked quand la politique est déjà chargée, et que montre l’extrait filtré de fixture-list.txt ?
La politique signée (ping-api-0 autorisé, ping-api-1 refusé) est déjà chargée lorsque l’opérateur envoie sur POST /admin/contracts le contrat ping-api déclarant /ping et /blocked.
À vous de prédire
Que renvoie POST /admin/contracts avec /ping et /blocked alors que la politique refusant ping-api-1 est déjà en mémoire ?
Révéler la réponse enregistrée
Trace intégrale de POST /admin/contracts : 2 routes et 2 outils créés après chargement de la politique.
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":2,"status":"ok","tools_generated":2}Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/admin/contracts" \
> -H "authorization: Bearer <STOA_ADMIN_API_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{"name":"ping-api","version":"1.0.0","tenant_id":"quickstart","status":"published","classification":"H","inboundAuth":"jwt","endpoints":[{"path":"/ping","methods":["GET"],"backend_url":"http://backend:80"},{"path":"/blocked","methods":["GET"],"backend_url":"http://backend:80"}]}'Console · Rejeu de trace enregistrée
Rejouez POST /mcp/tools/list sans jeton puis avec le jeton quickstart-caller :
Observez le 401 anonyme, puis l’extrait filtré (noms et descriptions, 6 outils sur 17) de fixture-list.txt (8046 o).
STOA Gateway (127.0.0.1:8892) · 1. POST /mcp/tools/list sans jeton
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 401
{"error":"unauthorized","message":"Missing Authorization header"}HTTP 401 intégral : {"error":"unauthorized","message":"Missing Authorization header"}.
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
> -H 'content-type: application/json' \
> -d '{}'STOA Gateway (127.0.0.1:8892) · 2. POST /mcp/tools/list avec jeton valide
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200
# fixture-list.txt (filtered excerpt: name + description only, 6 of 17 tools, 8046 bytes)
{"name":"stoa_platform_health","description":"Health check all platform components (Gateway, Keycloak, Database, Kafka)"}
{"name":"stoa_tools","description":"Tool discovery: list, schema, search"}
{"name":"uac:quickstart:ping-api:ping-api-0","description":"GET /ping — ping-api [quickstart]"}
{"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"}
{"name":"stoa_catalog","description":"API catalog: list, get, search, versions, categories. Returns paginated API listings with filtering support."}
{"name":"stoa_uac","description":"UAC contracts: list, get, validate, sla"}
# ... +11 built-in stoa_* tools (inputSchema and outer JSON omitted)HTTP 200 (extrait filtré : noms et descriptions de 6 outils sur 17 de fixture-list.txt, sans inputSchema ni JSON englobant) : uac:quickstart:ping-api:ping-api-1 apparaît bien qu’interdit.
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{}'Repérage dans la trace
Dans cet extrait filtré (noms et descriptions) de POST /mcp/tools/list, cliquez sur la ligne de l’outil interdit :
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200 # fixture-list.txt (filtered excerpt: name + description only, 6 of 17 tools, 8046 bytes) {"name":"stoa_platform_health","description":"Health check all platform components (Gateway, Keycloak, Database, Kafka)"} {"name":"stoa_tools","description":"Tool discovery: list, schema, search"} {"name":"uac:quickstart:ping-api:ping-api-0","description":"GET /ping — ping-api [quickstart]"} {"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"} {"name":"stoa_catalog","description":"API catalog: list, get, search, versions, categories. Returns paginated API listings with filtering support."} {"name":"stoa_uac","description":"UAC contracts: list, get, validate, sla"} # ... +11 built-in stoa_* tools (inputSchema and outer JSON omitted)
Voir la ligne attendue
{"name":"uac:quickstart:ping-api:ping-api-1","description":"GET /blocked — ping-api [quickstart]"} uac:quickstart:ping-api:ping-api-1 (GET /blocked) figure dans la liste HTTP 200 malgré allowed: false.
- Ces lignes indiquent HTTP 200 et l’extrait filtré (noms et descriptions, 6 outils sur 17).
- Ce sont quatre outils internes stoa_* ; regardez les entrées uac:quickstart:ping-api:*.
- ping-api-0 correspond à GET /ping (autorisé) ; regardez la ligne suivante.
Cherchez parmi les deux entrées uac:quickstart:ping-api:* celle liée à /blocked.
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/list" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{}'La règle Ni /health/ready en 200 ni la présence d’un outil dans POST /mcp/tools/list (17 outils en HTTP 200) ne valent droit d’exécution : sur ce commit, la liste inclut l’outil refusé.
Détail Expert : ordre de chargement, couple viewer + stoa:read et journaux
Trois points de lecture : (1) la politique JWS est chargée avant POST /admin/contracts ; (2) fixture-list.txt (8046 o) compte 17 outils (15 stoa_* internes + ping-api-0 et ping-api-1) ; (3) le jeton quickstart-caller porte rôle viewer et portée stoa:read sans séparation causale ni test de portée manquante ou d’autre locataire, et un code permission_absent dans les logs peut accompagner allowed: false.
Vérifiez vos acquis
Choisissez une réponse : la correction s’affiche aussitôt.
Que renvoie POST /mcp/tools/list avec un jeton valide lorsque ping-api-1 est marqué allowed: false ?
HTTP 200 avec 17 outils incluant ping-api-0 et ping-api-1 ; le refus s’applique lors de l’appel.
Bonne réponse. Exact : la liste n’élague pas l’outil refusé au commit 639e8b9a.
HTTP 200 en masquant automatiquement ping-api-1.
Pas tout à fait. Faux : ping-api-1 figure dans fixture-list.txt.
HTTP 200 même sans en-tête Authorization.
Pas tout à fait. Faux : sans Bearer, la route répond HTTP 401.
Que peut-on conclure du jeton quickstart-caller quant aux rôles et portées OIDC ?
Il porte viewer et scope=stoa:read : l’essai valide ce couple nominal sans les séparer causalement ni tester portée manquante ou second locataire.
Bonne réponse. Exact : on ne revendique pas l’effet isolé d’un paramètre non testé négativement.
Il prouve l’isolation entre deux locataires distincts.
Pas tout à fait. Faux : seul le locataire quickstart est exercé.
Leçon 3
Exécution d’outils : HTTP 403 sur /mcp/tools/call face au code JSON-RPC -32001 sous HTTP 200
Traces réelles capturées le 15 novembre 2026
Claire, DSI Quel risque prenons-nous si le suivi MCP ne regarde que les codes HTTP 200 en JSON-RPC ?
Mehdi, chef de projet API Comment distinguer en recette le refus sur POST /mcp/tools/call et sur POST /mcp ?
Nadia, architecte sécurité Quelle URL amont exacte l’outil dynamique appelle-t-il, et comment chaque route exprime-t-elle un refus ?
Lucas, ingénieur plateforme Quels statuts HTTP et corps JSON reviennent pour ping-api-0 et ping-api-1 sur /mcp/tools/call et /mcp ?
STOA Gateway expose POST /mcp/tools/call (HTTP simple) et POST /mcp (JSON-RPC 2.0 tools/call). Comparez les quatre réponses intégrales capturées pour ping-api-0 et ping-api-1.
Console · Rejeu de trace enregistrée
Comparez l’appel autorisé (ping-api-0) et refusé (ping-api-1) sur les deux routes MCP :
Alternez cible et scénario pour inspecter les quatre corps intégraux.
POST /mcp/tools/call (HTTP simple) · 1. Outil autorisé par la politique · uac:quickstart:ping-api:ping-api-0
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200
{"content":[{"type":"text","text":"<!DOCTYPE html>\n<html>\n<head>\n<title>Welcome to nginx!</title>\n<style>\nhtml { color-scheme: light dark; }\nbody { width: 35em; margin: 0 auto;\nfont-family: Tahoma, Verdana, Arial, sans-serif; }\n</style>\n</head>\n<body>\n<h1>Welcome to nginx!</h1>\n<p>If you see this page, the nginx web server is successfully installed and\nworking. Further configuration is required.</p>\n\n<p>For online documentation and support please refer to\n<a href=\"http://nginx.org/\">nginx.org</a>.<br/>\nCommercial support is available at\n<a href=\"http://nginx.com/\">nginx.com</a>.</p>\n\n<p><em>Thank you for using nginx.</em></p>\n</body>\n</html>\n"}]}HTTP 200 intégral : l’outil dynamique appelle le backend_url exact http://backend:80 (sa racine, sans ajouter le chemin /ping de la route contrat) et reçoit « Welcome to nginx! ».
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/call" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{"name":"uac:quickstart:ping-api:ping-api-0","arguments":{}}'POST /mcp/tools/call (HTTP simple) · 2. Outil refusé par la politique · uac:quickstart:ping-api:ping-api-1
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 403
{"content":[{"type":"text","text":"Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant"}],"isError":true}HTTP 403 intégral avec isError: true et « Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant ». Aucun appel vers http://backend:80.
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp/tools/call" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{"name":"uac:quickstart:ping-api:ping-api-1","arguments":{}}'POST /mcp (JSON-RPC 2.0) · 1. Outil autorisé par la politique · uac:quickstart:ping-api:ping-api-0
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200
{"jsonrpc":"2.0","result":{"content":[{"text":"<!DOCTYPE html>\n<html>\n<head>\n<title>Welcome to nginx!</title>\n<style>\nhtml { color-scheme: light dark; }\nbody { width: 35em; margin: 0 auto;\nfont-family: Tahoma, Verdana, Arial, sans-serif; }\n</style>\n</head>\n<body>\n<h1>Welcome to nginx!</h1>\n<p>If you see this page, the nginx web server is successfully installed and\nworking. Further configuration is required.</p>\n\n<p>For online documentation and support please refer to\n<a href=\"http://nginx.org/\">nginx.org</a>.<br/>\nCommercial support is available at\n<a href=\"http://nginx.com/\">nginx.com</a>.</p>\n\n<p><em>Thank you for using nginx.</em></p>\n</body>\n</html>\n","type":"text"}]},"id":2}HTTP 200 intégral : l’enveloppe JSON-RPC (id: 2) transporte dans result.content le HTML « Welcome to nginx! » de http://backend:80.
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"uac:quickstart:ping-api:ping-api-0","arguments":{}}}'POST /mcp (JSON-RPC 2.0) · 2. Outil refusé par la politique · uac:quickstart:ping-api:ping-api-1
Voir la réponse capturée
Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)
HTTP 200
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Tool call rejected","data":{"httpStatus":403,"result":{"content":[{"text":"Tool 'uac:quickstart:ping-api:ping-api-1' is not allowed for this tenant","type":"text"}],"isError":true}}},"id":3}Subtilité clé : transport HTTP 200, mais corps JSON-RPC (id: 3) en error.code = -32001 (« Tool call rejected ») et error.data.httpStatus = 403 (isError: true).
Voir la commande curl équivalente (reproduction avec -w)
$ curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://127.0.0.1:8892/mcp" \
> -H "authorization: Bearer <ACCESS_TOKEN>" \
> -H 'content-type: application/json' \
> -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"uac:quickstart:ping-api:ping-api-1","arguments":{}}}'Classement
Associez chaque comportement vérifié à l’interface correspondante de STOA Gateway :
- Exprime le refus de politique dès le statut transport HTTP 403 avec isError: true.
Voir la réponse
POST /mcp/tools/call (route HTTP simple). Sur /mcp/tools/call, le refus de ping-api-1 renvoie directement HTTP 403.
- Renvoie HTTP 200 en plaçant le refus dans error.code = -32001 et error.data.httpStatus = 403.
Voir la réponse
POST /mcp (enveloppe JSON-RPC 2.0). Sur POST /mcp, ne vérifier que HTTP 200 masque le rejet -32001.
- Contrôle santé CP/OIDC configurée et atteste notamment la politique disponible en 200 READY, sans tout autoriser.
Voir la réponse
GET /health/ready (sonde d’orchestration). READY atteste santé et politique disponible ; chaque appel reste filtré.
- Renvoie en succès (id: 2) un objet JSON-RPC contenant result.content.
Voir la réponse
POST /mcp (enveloppe JSON-RPC 2.0). L’appel JSON-RPC autorisé renvoie HTTP 200 avec result.content.
La règle Un refus d’outil renvoie HTTP 403 sur POST /mcp/tools/call mais HTTP 200 avec error.code = -32001 (data.httpStatus = 403) sur POST /mcp : inspectez toujours le corps JSON-RPC sans extrapoler hors du locataire testé.
Détail Expert : racine http://backend:80, erreur -32001 et limites hors preuve
L’outil dynamique appelle le backend_url exact http://backend:80 (sa racine) et non le chemin /ping de l’endpoint contrat. Sur POST /mcp, fixture-rpc-denied.txt renvoie error.code = -32001 et error.data.httpStatus = 403 sous HTTP 200. Non testés : Control Plane de production, isolation inter-locataires, portée manquante et expiration TTL.
Vérifiez vos acquis
Choisissez une réponse : la correction s’affiche aussitôt.
Un test appelle ping-api-1 sur POST /mcp (JSON-RPC) et ne teste que « HTTP == 200 ». Que conclut-il à tort ?
Il croit l’appel autorisé alors qu’il est rejeté avec error.code = -32001 et error.data.httpStatus = 403 sous HTTP 200.
Bonne réponse. Exact : le rejet applicatif JSON-RPC se lit dans error malgré HTTP 200.
Il reçoit un statut HTTP 403 comme sur POST /mcp/tools/call.
Pas tout à fait. Non : seul POST /mcp/tools/call répond HTTP 403.
Il reçoit le HTML de http://backend:80 avec un avertissement.
Pas tout à fait. Non : l’appel refusé n’atteint jamais le backend.
Cas de décision
Claire, DSI Avant un pilote MCP chez Hélios Distribution, quelles décisions factuelles validez-vous ?
Mehdi, chef de projet API Pour le plan de recette MCP, quelles exigences prouvées retenez-vous ?
Nadia, architecte sécurité En revue d’architecture MCP, quels garde-fous et réserves actez-vous ?
Lucas, ingénieur plateforme Dans vos tests automatisés sur stoa-gateway, quelles assertions combinez-vous ?
Plusieurs réponses comptent. Choisissez-les toutes.
Cas de décision
Claire, DSI GET /health/ready reste en 503 au démarrage avec STOA_POLICY_BOOT_TENANTS=quickstart. Que faites-vous vérifier ?
Mehdi, chef de projet API En intégration, /health/ready reste en 503 malgré Keycloak actif. Quel contrôle priorisez-vous ?
Nadia, architecte sécurité STOA Gateway maintient /health/ready en 503 à l’amorçage. Quelle chaîne inspectez-vous ?
Lucas, ingénieur plateforme Avec STOA_POLICY_BOOT_TENANTS=quickstart, /health/ready reste en 503. Que contrôlez-vous ?
Une seule réponse tient. Choisissez-la.
La décision de l’équipe
Hélios retient les traces du banc pour le pilote. Les critères incluent le résultat JSON-RPC et des tests sur le Control Plane cible.
Ce que prouve la trace. Captures Python urllib du banc : /health/ready passe de 503 à 200, la liste montre les deux outils et l’appel de ping-api-1 est refusé.
À retenir
- Le fournisseur de laboratoire fournit le JWS Ed25519. Sur ce banc, /health/ready répond 503 avec une signature altérée et 200 avec une signature valide.
- Ni /health/ready en 200 ni la présence d’un outil dans POST /mcp/tools/list (17 outils en HTTP 200, dont uac:quickstart:ping-api:ping-api-1) n’autorisent son exécution.
- L’outil autorisé appelle la racine http://backend:80 ; l’outil interdit est rejeté en HTTP 403 (/mcp/tools/call) ou -32001 sous HTTP 200 (/mcp) — sans qualifier le Control Plane produit, l’isolation inter-locataires ni l’expiration TTL.
À reproduire sur votre poste (Docker local)
Reproduire le banc MCP à fournisseur CP de labo dans un dossier neuf (tools/run-lab-m2.sh)
Exécuter depuis la racine du projet une reproduction locale isolée au commit propre 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 via tools/run-lab-m2.sh : STOA Gateway (tag personnel éphémère) et Keycloak 26.5.3 réels, control-plane remplacé par une copie locale de policy_fixture.py, secrets en dossier 0700 supprimés même sur échec, sans toucher verification-module-2/ ni references/.
- Prérequis
- Docker Compose v2 actif + python3 avec cryptography (clés du fournisseur CP local) · Ports 127.0.0.1:8890–8892 libres et aucun projet stoa-lab-m2-* actif · Build passerelle variable à froid (5 à 15 min selon machine/réseau, ~1 min avec cache chaud)
- Durée estimée
- Build variable + ~1 min de recette MCP
Commande et guide de vérification locale
bash tools/run-lab-m2.sh --prepare-only --out .lab-test/m2-prep bash tools/run-lab-m2.sh --out .lab-test/m2-essai-1 cat .lab-test/m2-essai-1/fixture-audit.json cat .lab-test/m2-essai-1/fixture-call-denied.txt .lab-test/m2-essai-1/fixture-rpc-denied.txt
Wrapper copiant les scripts qualifiés de verification-module-2/ dans un dossier neuf (projet stoa-lab-m2-*, tag passerelle personnel nettoyé, *_TIMEOUT bornés et suppression try/finally du dossier 0700).
- Préparez un dossier neuf sans Docker (vérifie commit propre, délais positifs et copie isolée du fournisseur CP et du runner) :
bash tools/run-lab-m2.sh --prepare-only --out .lab-test/m2-prep
- Lancez le banc dans un dossier neuf (ports 127.0.0.1:8890–8892 libres, tag <projet>-gateway:639e8b9a construit si absent, Keycloak, nginx, policy_fixture.py et STOA Gateway) :
bash tools/run-lab-m2.sh --out .lab-test/m2-essai-1
- Vérifiez fixture-audit.json (503 -> 200, 201, 401/200, 200/403 et JSON-RPC 200/-32001) et les corps de refus :
cat .lab-test/m2-essai-1/fixture-audit.json cat .lab-test/m2-essai-1/fixture-call-denied.txt .lab-test/m2-essai-1/fixture-rpc-denied.txt
- Contrôlez la suppression de .runtime-fixture (0700) et l’absence de conteneur stoa-lab-m2-* :
ls -la .lab-test/m2-essai-1 cat .lab-test/m2-essai-1/remaining-containers.txt
Vous avez réussi si fixture-audit.json valide tous les contrôles (503 -> 200, 201, 401, 200, 200, 403 et rpcDenied -32001/403), .runtime-fixture est supprimé, les logs sont purgés des secrets/JWT, remaining-containers.txt est vide et verification-module-2/ est intact.
Appliquer
Et chez vous ?
Posez-vous ces questions sur votre propre organisation. Vos coches et vos notes ne sont ni envoyées ni enregistrées : imprimez-les ou copiez-les.
Claire, DSI
- Exigeons-nous la preuve d’un outil MCP refusé à côté d’un outil autorisé en démonstration ?
- Séparons-nous la preuve sur STOA Gateway réelle du fournisseur CP de laboratoire ?
- Nos métriques MCP suivent-elles le code JSON-RPC -32001 plutôt que le seul HTTP 200 ?
- Avons-nous prévu des essais dédiés avant toute promesse multi-locataires ou d’expiration TTL ?
Mehdi, chef de projet API
- Nos critères rappellent-ils qu’un outil présent dans POST /mcp/tools/list reste bloqué à l’appel s’il est interdit ?
- Nos tests couvrent-ils POST /mcp/tools/call (403) et POST /mcp en JSON-RPC (HTTP 200 avec -32001) ?
- Le 405 observé avec l’image control-plane-api:1.14.1 épinglée est-il tracé avant d’intégrer le Control Plane cible ?
- Les ports 8890–8892 et le build Rust variable sont-ils documentés ?
Nadia, architecte sécurité
- Comment distribuons-nous le JWKS épinglé Ed25519 (STOA_POLICY_TRUST_JWKS_FILE) et la clé RSA d’authentification client private_key_jwt ?
- Nos orchestrateurs exploitent-ils GET /health/ready en connaissant ses contrôles CP, OIDC et politique ?
- Nos clients MCP traitent-ils error.code = -32001 et isError: true sous HTTP 200 ?
- Quels tests couvriront un second locataire, la portée manquante et l’expiration TTL ?
Lucas, ingénieur plateforme
- Testons-nous le 503 sur signature JWS altérée avant de valider 200 READY ?
- Isolons-nous chaque essai dans stoa-lab-m2-* avec tag personnel et suppression try/finally du dossier 0700 ?
- Nos tests CI vérifient-ils HTTP 403 sur /mcp/tools/call et error.data.httpStatus == 403 sur /mcp ?
- Vérifions-nous l’absence de jeton ou clé privée dans les journaux collectés ?
Fin du module 2
Bilan du module 2 : politiques signées, exécution MCP filtrée et limites explicites
Le banc avec STOA Gateway, Keycloak et le fournisseur de laboratoire montre les deux états de la sonde ainsi que l’appel autorisé et le refus.
- Expliquer ce que contrôle /health/ready (santé CP/OIDC et politique disponible en 200 READY après signature Ed25519 valide) et pourquoi Compose utilise un fournisseur CP de labo.
- Prouver sur trace que ni /health/ready en 200 ni ping-api-1 dans POST /mcp/tools/list (HTTP 200) n’autorisent son exécution.
- Vérifier les deux refus MCP : HTTP 403 sur POST /mcp/tools/call et erreur JSON-RPC -32001 (data.httpStatus: 403) sous HTTP 200 sur POST /mcp.
- Garder hors des affirmations non prouvées le Control Plane produit, l’isolation inter-locataires, la portée manquante et l’expiration TTL.
Pour aller plus loin
Retrouvez les deux modules sur la fiche du cours. En parcours Expert, bash tools/run-lab-m2.sh relance le banc sur 127.0.0.1:8890–8892.
Revoir le programmeDocumentation STOA (docs.gostoa.dev) ↗Démo en ligne STOA ↗