Formations · Contrôler l’accès à une API avec STOA
FORMATION PRODUIT STOA · Contrôle d’accès API, API & agents IA, Gouvernance & preuve
Contrôler l’accès à une API avec STOA
Suivez Hélios dans deux modules gratuits. Rejouez les contrôles JWT d’une route REST et les décisions d’une politique d’outils MCP sur des traces de laboratoire.
- Public
- DSI & Direction technique, Chefs de projet & Product Owners, Architectes & Sécurité, Ingénieurs API & Plateforme
- Niveau
- Fondamentaux
- Durée
- 35–40 min · sans installation
- Accès
- 2 modules gratuits · accès direct
- Trace vérifiée
Vérifié sur des essais locaux le 15 novembre 2026. Voir le détail vérifié ↓
LE PROGRAMME
Le programme, module par module
01Première API protégée : filtrer les accès et cadrer un piloteAccès libre
Objectif. Sur la route testée, comparez les deux refus obtenus sans jeton ou avec un jeton invalide et la réponse du service amont avec un jeton valide.
Voir le détail vérifié
Première API protégée : contrat, preuve 401/401/200 et limites du quickstart. Lire les réponses observées sur GET /apis/quickstart/ping-api/ping après la déclaration du contrat sur STOA Gateway : HTTP 401 sans jeton, HTTP 401 avec un jeton invalide et HTTP 200 avec un JWT Keycloak valide. Relever aussi le HTTP 503 renvoyé par /health/ready dans ce montage.
- Déclarer le contrat directement sur STOA Gateway6 min
- Prouver le contrôle d’accès : la séquence 401 / 401 / 200 sans rien inventer6 min
- Validation JWT locale (JWKS), portée du claim tenant_id et limite /health/ready (503)5 min
02Agents IA : quels outils peuvent-ils exécuter ?Accès libre
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.
- Image Control Plane épinglée (405), politique Ed25519 et bascule /health/ready de 503 à 2006 min
- Contrat à deux endpoints, découverte POST /mcp/tools/list et présence de l’outil interdit7 min
- Exécution d’outils : HTTP 403 sur /mcp/tools/call face au code JSON-RPC -32001 sous HTTP 2006 min
Architecture et accès
Vue d’ensemble de STOA
JWT et politique MCP
À L’ARRIVÉE
Prendre une décision d’exposition API appuyée sur des preuves vérifiables
- Lire les preuves de contrôle d’accès sur une route REST pilote.
- Distinguer les outils visibles des outils qu’un agent peut exécuter.
Voir le détail vérifié
- Relier la déclaration du contrat JWT (POST /admin/contracts) aux trois réponses 401 / 401 / 200 observées sur la route REST. Distinguer ces réponses de celle de la sonde /health/ready (503).
- Valider une politique d’outils MCP signée Ed25519 via un JWKS épinglé (bascule /health/ready de 503 à 200 READY sur fournisseur CP de laboratoire), distinguer visibilité dans POST /mcp/tools/list et exécution autorisée, et lire les refus HTTP 403 (/mcp/tools/call) ou JSON-RPC -32001 sous HTTP 200 (/mcp).
POUR QUI
Cette formation est pour vous si
- Les DSI et directions techniques qui veulent évaluer sur preuves réelles ce que protège — et ne couvre pas encore — une passerelle API et agents IA.
- Les chefs de projet et Product Owners qui cadrent les critères d’acceptation avant l’ouverture d’un service à un partenaire.
- Les architectes et responsables sécurité qui examinent le contrôle d’accès et les sondes de disponibilité.
- Les équipes plateforme qui souhaitent parcourir les preuves dans le navigateur, puis reproduire les essais sur leur poste si nécessaire.
Elle n’est pas pour vous si
- Les équipes cherchant une initiation générale aux API ou aux conteneurs sans lien avec STOA.
- Les organisations qui cherchent une qualification de leur environnement de production.
Voir le détail vérifié
Cette formation est pour vous si
- Les DSI et responsables techniques qui veulent valider factuellement ce que prouve — et ne prouve pas encore — une démonstration de passerelle API.
- Les chefs de projet et Product Owners qui cadrent les critères d’acceptation d’une première route REST protégée.
- Les architectes et référents sécurité qui examinent la validation JWT locale par cache JWKS, les revendications OIDC et les sondes d’exploitation.
- Les ingénieurs API et plateforme qui souhaitent rejouer les traces hors ligne puis relancer le labo isolé via tools/run-lab.sh sur 127.0.0.1.
Elle n’est pas pour vous si
- Les équipes cherchant un cours généraliste d’introduction à REST ou à Docker sans lien avec STOA.
- Les équipes qui cherchent une qualification du Control Plane de production ou de leur fournisseur d’identité d’entreprise.
LES DEUX MODULES SONT GRATUITS
Commencez directement dans votre navigateur
Suivez les deux modules dès « Première API protégée : filtrer les accès et cadrer un pilote » dans le navigateur. Rejouez les traces en parcours Décideur ou Expert, puis utilisez les guides pour reproduire les essais Docker si vous le souhaitez.
Commencer le module 1CONCEPTION PÉDAGOGIQUE
Équipe pédagogique STOA Learn
Ingénierie passerelle & gouvernance API
Ce parcours met les décideurs et les équipes techniques autour des mêmes preuves : une lecture interactive dans le navigateur sans installation ni appel externe pendant le rejeu, complétée par des bancs locaux reproductibles pour vos ingénieurs.
Voir le détail vérifié
Les deux modules s’appuient sur le commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 et sur des captures locales. Le module 1 suit le quickstart STOA. Le module 2 associe STOA Gateway et Keycloak à un fournisseur Control Plane de laboratoire identifié.
QUESTIONS FRÉQUENTES
Avant de vous lancer
De quoi ai-je besoin pour suivre les deux modules ?
Le parcours gratuit dure 35 à 40 minutes dans le navigateur. Les captures sont rejouées localement, sans appel externe. La reproduction facultative des essais demande Docker et un accès réseau au premier build pour télécharger les images et les crates Rust.
Pourquoi le module 2 utilise-t-il un fournisseur Control Plane de laboratoire ?
Au commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913, la passerelle attend un artefact JWS signé Ed25519. Le GET /v1/tenants/quickstart/tool-permissions/artifact a renvoyé HTTP 405 lors de l’essai avec l’image control-plane-api:1.14.1 épinglée. Dans le second montage, policy_fixture.py signe et sert l’artefact et répond à /health et aux requêtes minimales de découverte de STOA Gateway.
Pourquoi la durée de compilation du labo est-elle indiquée comme une estimation variable ?
Dans le quickstart officiel, les images de base sont tirées par digest SHA-256 et stoa-gateway est compilée en Rust (cargo build --release --locked) dans un tag personnel du projet de laboratoire. À froid, téléchargements et compilation prennent typiquement 5 à 15 minutes selon la machine et la bande passante, contre environ une minute avec un cache Docker chaud.
D’où viennent les réponses HTTP et les commandes affichées ?
Au module 1, verify.sh exécute curl. Au module 2, Python urllib enregistre le statut HTTP et le corps de la réponse. Les commandes curl -w du module 2 sont des équivalents pour reproduire les requêtes. Les extraits sont signalés dans les leçons.
Quelles données sont conservées pendant que je parcours les modules ?
Uniquement votre choix de rôle, votre choix de parcours (Décideur ou Expert) et les étapes franchies par module, dans le stockage local de votre navigateur (clé stoa-learn). Aucun cookie ni appel externe n’est émis pendant le rejeu, et le bouton « Effacer ma progression » remet tout à zéro.
PÉRIMÈTRE DES ESSAIS
Ce que couvrent les traces
Les deux modules s’appuient sur des essais locaux. Voici les limites à prendre en compte avant d’appliquer les résultats à votre environnement.
- Le plan de contrôle produit complet, l’authentification forte humaine d’entreprise (MFA) et le déploiement haute disponibilité ne sont pas qualifiés par ces essais locaux.
- Dans le montage minimal du module 1, la sonde de disponibilité reste en attente faute de politique d’outils chargée.
- Le module 2 utilise un service de signature de laboratoire après le refus de la demande d’artefact signé par l’image du plan de contrôle épinglée pour l’essai.
Voir le détail vérifié
- Image épinglée control-plane-api:1.14.1 : GET /v1/tenants/quickstart/tool-permissions/artifact a renvoyé HTTP 405 Method Not Allowed. Le module 2 remplace le service control-plane de Compose par policy_fixture.py pour tester l’amorçage de la politique.
- Sonde de disponibilité M1 : GET /health/ready répond HTTP 503 (NOT READY: tool policy unavailable) tant qu’aucune politique d’outils signée Ed25519 n’est chargée via STOA_POLICY_TRUST_JWKS_FILE.
- Découverte vs exécution MCP (M2) : POST /mcp/tools/list (HTTP 200, 17 outils) expose aussi l’outil interdit uac:quickstart:ping-api:ping-api-1 ; son exécution est refusée en HTTP 403 sur POST /mcp/tools/call et en code JSON-RPC -32001 (data.httpStatus: 403) sous HTTP 200 sur POST /mcp.
- Service amont des deux essais : nginx 1.27.5-alpine de laboratoire, sans données métier.
PROVENANCE & PREUVES
Ce qui a été vérifié sur le banc réel
Vérifié sur des essais locaux le 15 novembre 2026.
Voir le détail vérifié
- Essais locaux du 15 novembre 2026 sur le commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 de stoa-platform/stoa. Versions du banc : plateforme 2.3.0 déclarée dans les sources, stoa-gateway 0.9.25, control-plane-api 1.14.1, Keycloak 26.5.3, PostgreSQL 16.10-alpine et nginx 1.27.5-alpine. Le module 2 utilise le fournisseur Control Plane de laboratoire policy_fixture.py.
- Au module 1, POST /admin/contracts renvoie HTTP 201 (routes_generated: 1, tools_generated: 1). La route REST GET /apis/quickstart/ping-api/ping renvoie HTTP 401 sans jeton, HTTP 401 avec Bearer invalid et HTTP 200 avec un JWT Keycloak valide vérifié localement via JWKS. Dans ce montage, GET /health/ready reste en HTTP 503.
- Dans le banc initial du module 2, GET /v1/tenants/quickstart/tool-permissions/artifact renvoie HTTP 405 Method Not Allowed sur l’image control-plane-api:1.14.1 épinglée au digest sha256:a8c01bfac64865f543f7836d6b3f1e626896817913c47715b240760bd3f58c81.
- Module 2 (STOA Gateway et Keycloak réels + service control-plane complet remplacé dans Compose par un fournisseur CP de laboratoire explicite assurant la signature JWS, /health et trois réponses minimales de découverte) : signature JWS altérée rejetée en HTTP 503 sur /health/ready, JWS valide ouvrant /health/ready en HTTP 200 READY, POST /mcp/tools/list (401 sans jeton, 200 listant 17 outils dont l’outil refusé), exécution autorisée en 200 vers http://backend:80 et refus en HTTP 403 sur POST /mcp/tools/call ou code JSON-RPC -32001 (data.httpStatus: 403) sous HTTP 200 sur POST /mcp.
- Les essais utilisent nginx comme service amont de laboratoire, sans données métier. La qualification du Control Plane de production et de sa synchronisation exige des essais sur l’environnement cible.
DÉPLOIEMENT & ÉQUIPES
Tester sur vos API,
avec vos équipes.
Le parcours Expert fournit les étapes pour reproduire les essais REST et MCP sur un banc Docker local. Retrouvez les autres options de configuration dans la documentation STOA.
Explorer la documentation STOA