STOA Learn

Formations · Contrôler l’accès à une API avec STOA

Module 2 sur 2 · Accès libre

Comprendre ce qu’un agent IA est autorisé à exécuter

Agents IA : quels outils peuvent-ils exécuter ?

Objectif. Distinguer les outils visibles dans le catalogue de ceux qu’un agent IA peut exécuter, et vérifier comment un refus remonte.

Voir le détail vérifié

Politiques d’outils MCP, exécution d’outils et sonde /health/ready. Observer comment une politique signée affecte la sonde /health/ready et l’exécution de deux outils MCP sur le banc STOA Gateway et Keycloak.

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.

Extrait de la trace enregistrée Banc MCP local · /mcp/tools/call : appel permis, HTTP 200. Appel refusé par la politique, HTTP 403.
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. »

Plutôt d’accord

À nuancer. Piège classique : /health/ready contrôle la santé CP/OIDC configurée et atteste notamment une politique disponible, et POST /mcp/tools/list renvoie tous les outils enregistrés — même refusés.

Plutôt pas d’accord

L’essai va dans votre sens. Exact : ping-api-1 figure dans la réponse HTTP 200 de POST /mcp/tools/list, mais son exécution est bloquée par la politique chargé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.

Banc M2 : STOA Gateway et Keycloak réels + fournisseur CP de labo
Banc M2 : STOA Gateway et Keycloak réels + fournisseur CP de laboCinq étapes : chargement JWS Ed25519 depuis le fournisseur CP de labo, contrat à 2 endpoints, liste de 17 outils, contrôle JWT + politique, et appel de http://backend:80 pour le seul outil autorisé.1. JWS signé2. Contrat3. tools/list4. JWT + Policy5. :80fournisseur CP laboJWS Ed25519Client MCPAdmin & appelskeycloakRealm & servicegatewayRust 0.9.25backendnginx 1.27.5
  1. 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.
  2. 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).
  3. Avec le jeton quickstart-caller, POST /mcp/tools/list renvoie HTTP 200 avec 17 outils, dont ping-api-0 et ping-api-1.
  4. Dans les traces, les appels avec le JWT du locataire quickstart sont soumis à la politique signée, sur /mcp/tools/call et /mcp.
  5. Seul ping-api-0 (allowed: true) appelle la racine http://backend:80 ; ping-api-1 (allowed: false) est bloqué en amont.
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 ?

HTTP 200 avec un jeton JWS Ed25519 signé.

Pas tout à fait. Non : cette route d’export signé est absente de control-plane-api:1.14.1.

HTTP 405 avec {"detail":"Method Not Allowed"} (OpenAPI de l’image épinglée sans /tool-permissions/artifact).

Bonne réponse. Exact : cet écart sur l’image non modifiée justifie le remplacement du service control-plane par un fournisseur CP de labo identifié.

HTTP 500 causé par PostgreSQL.

Pas tout à fait. Non : l’image control-plane-api:1.14.1 épinglée a renvoyé 200 sur /health et 405 sur la requête d’artefact.

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é
  1. 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.
  2. 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.
  3. 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.
  4. 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 ?

HTTP 200 « READY », attestant notamment la politique disponible sans autoriser tous les outils.

Bonne réponse. Exact : le handler contrôle santé CP/OIDC configurée et état de la politique, puis répond READY.

HTTP 200 listant en JSON les outils autorisés.

Pas tout à fait. Non : /health/ready renvoie uniquement READY.

HTTP 503 tant qu’aucun client n’appelle POST /mcp.

Pas tout à fait. Non : readiness ne dépend pas du trafic client.

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

Trace intégrale de GET /health/ready sous signature JWS altérée : HTTP 503.

Capture Python urllib du 15 novembre 2026 (statut et corps, sans en-têtes)

HTTP 503
NOT READY: tool policy unavailable
Voir 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 ?

HTTP 403, car le second endpoint est refusé par la politique active.

Pas tout à fait. Non : la politique filtre l’exécution MCP, pas l’enregistrement du contrat.

HTTP 201 avec routes_generated: 2 et tools_generated: 2 pour quickstart:ping-api.

Bonne réponse. Exact : les deux routes et descripteurs d’outils (ping-api-0 et ping-api-1) sont créés.

HTTP 201 avec tools_generated: 1 en filtrant l’outil interdit.

Pas tout à fait. Non : tools_generated vaut 2.

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

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

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

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

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

Tester un appel autorisé ET un appel refusé (ping-api-0 en 200, ping-api-1 rejeté), sans déduire les droits de POST /mcp/tools/list ni du 200 de /health/ready.

À retenir. Indispensable : la liste inclut l’outil interdit et READY n’accorde pas tous les outils.

Sur POST /mcp (JSON-RPC), vérifier l’absence de error (et attendre -32001 / httpStatus: 403 en test négatif) plutôt que le seul HTTP 200.

À retenir. Essentiel : le refus JSON-RPC voyage sous HTTP 200.

Affirmer que control-plane-api:1.14.1 sert l’artefact signé et que l’isolation inter-locataires est prouvée.

À écarter. Faux : la requête d’artefact a renvoyé 405 sur l’image épinglée et le second banc utilise un fournisseur de laboratoire et seul quickstart est testé.

Documenter le fournisseur CP de laboratoire et planifier des tests dédiés pour le Control Plane cible et le multi-locataires.

À retenir. Rigoureux : distinguer passerelle réelle et fournisseur CP de labo évite tout angle mort.

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.

Contrôler santé CP/OIDC, réponse 200 sur GET /v1/tenants/quickstart/tool-permissions/artifact (non 405), JWKS épinglé Ed25519 (STOA_POLICY_TRUST_JWKS_FILE) et authentification client private_key_jwt (RSA).

À retenir. Exact : dépendance indisponible, route 405 ou signature JWS invalide maintient /health/ready en 503.

Basculer readinessProbe sur GET /health pour masquer le 503.

À écarter. Dangereux : cela masque l’absence de politique chargée.

Publier d’autres contrats sur POST /admin/contracts pour débloquer /health/ready.

À écarter. Inutile : /health/ready ne dépend pas des contrats déclarés.

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

  1. 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.
  2. 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.
  3. 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).

  1. 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
  2. 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
  3. 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
  4. 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.