STOA Learn

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.

Parcours dans votre navigateur (Décideur ou Expert)35 à 40 minutes au total · aucun appel externe pendant le rejeu
Bancs locaux reproductibles (facultatif, parcours Expert)Relance guidée sur poste de travail avec Docker si vos équipes techniques souhaitent reproduire chaque essai (environ 5 à 15 min à froid)
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 pilote3 leçons · 15–20 min (lecture locale)Accè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.

  1. Déclarer le contrat directement sur STOA Gateway6 min
  2. Prouver le contrôle d’accès : la séquence 401 / 401 / 200 sans rien inventer6 min
  3. Validation JWT locale (JWKS), portée du claim tenant_id et limite /health/ready (503)5 min
Ouvrir le module gratuit
02Agents IA : quels outils peuvent-ils exécuter ?3 leçons · 20 min (lecture locale)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.

  1. Image Control Plane épinglée (405), politique Ed25519 et bascule /health/ready de 503 à 2006 min
  2. Contrat à deux endpoints, découverte POST /mcp/tools/list et présence de l’outil interdit7 min
  3. Exécution d’outils : HTTP 403 sur /mcp/tools/call face au code JSON-RPC -32001 sous HTTP 2006 min
Ouvrir le module gratuit

Architecture et accès

Vue d’ensemble de STOA

Keycloak émet les jetons des clients et agents MCP. La passerelle STOA vérifie les jetons à l’aide des clés JWKS, expose les routes et outils des tenants et relaie les appels autorisés vers les backends. Le fournisseur de plan de contrôle du banc M2 fournit la politique MCP signée.
Keycloak émet les JWT des clients REST et des agents MCP et publie les clés JWKS. La passerelle achemine les appels autorisés vers les backends. Sur le banc M2, un fournisseur de labo joue le rôle du plan de contrôle et fournit la politique MCP signée du tenant.

JWT et politique MCP

La passerelle vérifie le jeton avec les clés JWKS de Keycloak. Sur la route REST testée, un jeton absent ou invalide donne HTTP 401 et un jeton valide permet le transfert au backend. Sur le banc MCP, la règle signée de l’outil décide ensuite s’il peut être appelé.
La passerelle traite l’accès à la route REST testée selon le JWT. Sur le banc MCP, une politique décide si l’appel à un outil est permis.

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

CONCEPTION 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