STOA Learn

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

Module 1 sur 2 · Accès libre

Décider si une première route API peut être ouverte à un partenaire

Première API protégée : filtrer les accès et cadrer un pilote

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.

Repères du module · Repère rapide

Votre objectif dans ce module (15 à 20 min)

Évaluer sur un cas concret si l’ouverture d’une première route API protège bien votre service interne. Choisissez votre rôle en haut de page : le parcours Décideur se suit sans commande ni installation, et le parcours Expert affiche les commandes exactes.

Extrait de la trace enregistrée Quickstart local · Route testée : sans JWT et JWT invalide, HTTP 401. JWT valide, HTTP 200.
Voir le détail vérifié

Comment parcourir ce module en 15 à 20 minutes

Choisissez en haut de page le rôle métier le plus proche du vôtre : les questions s’adaptent, tandis que les preuves techniques demeurent strictement identiques.

Basculez librement entre le parcours Décideur (aucune commande, centré sur l’architecture, la preuve et les limites) et le parcours Expert (commandes curl exactes, détails d’implémentation et wrapper local tools/run-lab.sh).

Chaque sortie affichée dans ce module est un rejeu local identifié des fichiers capturés lors de la vérification réelle du quickstart STOA : aucun appel externe n’est émis pendant le rejeu.

Le cas · entreprise fictive

Hélios Distribution ouvre un point de vérification logistique à un premier partenaire

Hélios Distribution prépare l’ouverture d’une route API logistique à un transporteur pilote. L’équipe vérifie comment cette route répond selon le jeton présenté.

Voir le détail vérifié

Hélios Distribution exploite un catalogue de stocks interne et prépare l’ouverture d’une première route REST à un transporteur pilote, avant d’envisager plus tard l’exposition d’outils MCP.

L’équipe plateforme a exécuté le quickstart STOA avec le plan de contrôle, la passerelle, Keycloak, PostgreSQL et nginx. Elle a soumis trois requêtes à la même route pilote avec un jeton absent, invalide puis valide.

Avant d’autoriser un pilote, la direction technique exige une preuve reproductible des rejets et des succès sur un commit précis, ainsi qu’un inventaire rigoureux de ce que l’essai démontre et de ce qu’il ne teste pas encore.

Autour de la table, chacun pose la question de son métier.

  • Claire, DSI Que montrent les trois réponses de la route pilote et quelles vérifications devons-nous consigner avant d’élargir le pilote ?
  • Mehdi, chef de projet API Quels critères d’acceptation vérifiables dois-je mettre dans le ticket de recette en distinguant le rejeu local rapide et la durée variable d’un build Docker ?
  • Nadia, architecte sécurité Quel script déclare réellement la route sur la passerelle, comment la signature JWT est-elle vérifiée avec JWKS, et pourquoi /health/ready reste-t-elle en 503 ?
  • Lucas, ingénieur plateforme Quel payload exact reçoit stoa-gateway, quels corps reviennent en 201/401/200/503, et comment relancer un labo propre avec tools/run-lab.sh sans toucher aux preuves ?

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 le service Control Plane STOA démarre dans le quickstart, il déclare et protège automatiquement la route API sur la passerelle par jeton JWT. »

Plutôt d’accord

À nuancer. C’est l’intuition courante face à un plan de contrôle, mais comme l’indique explicitement quickstart/docker-compose.yml (R1), le Control Plane tourne sans déclarer ni protéger la route sur la passerelle.

Plutôt pas d’accord

L’essai va dans votre sens. Exact : dans le quickstart vérifié, c’est verify.sh qui envoie directement un contrat sur POST /admin/contracts de STOA Gateway (avec status: "published" et inboundAuth: "jwt") pour créer la route REST dynamique et activer le filtre JWT.

Voir ce que montre l’essai

Sur le banc quickstart vérifié (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), verify.sh appelle directement POST /admin/contracts sur stoa-gateway avec authorization: Bearer <STOA_ADMIN_API_TOKEN> : la réponse HTTP 201 annonce routes_generated = 1 et tools_generated = 1 pour la clé quickstart:ping-api (seule la route REST étant ensuite testée).

Leçon 1

Déclarer le contrat directement sur STOA Gateway

Traces réelles capturées le 15 novembre 2026

Claire, DSI Quel composant valide le jeton sur la route pilote et comment ce contrôle est-il activé dans le laboratoire ?

Mehdi, chef de projet API Quelle action crée effectivement le point d’entrée REST protégé que nous allons recetter ?

Nadia, architecte sécurité Quel est le rôle réel de chaque conteneur lors de l’ouverture de la route dans ce quickstart R1 ?

Lucas, ingénieur plateforme Que renvoie exactement l’appel POST /admin/contracts envoyé par verify.sh à stoa-gateway et comment les cinq conteneurs sont-ils assemblés ?

Dans le montage quickstart STOA, cinq services tournent sur un réseau Docker isolé : postgres, control-plane, keycloak, gateway et un conteneur amont nommé backend (nginx). Regardez attentivement qui envoie l’appel d’administration qui crée la route dans cette révision R1.

Chaîne réelle exécutée par verify.sh dans le quickstart STOA
Chaîne réelle exécutée par verify.sh dans le quickstart STOASchéma en cinq étapes : control-plane démarré hors chemin de déclaration, déclaration directe du contrat par verify.sh sur gateway, obtention du jeton Keycloak, appel GET /ping, validation locale via cache JWKS et transfert vers backend.1. /admin2. Jeton3. GET /ping4. Cache JWKS5. :80control-planeDémarré (hors R1)verify.shClient & AdminkeycloakRealm quickstartgatewayRust 0.9.25backendnginx 1.27.5
  1. verify.sh envoie directement POST /admin/contracts à STOA Gateway (tenant_id: quickstart, status: published, inboundAuth: jwt, backend_url: http://backend:80), tandis que control-plane reste hors de ce câblage R1.
  2. verify.sh demande un jeton d’accès au realm quickstart de Keycloak via le flux client_credentials.
  3. verify.sh interroge GET /apis/quickstart/ping-api/ping à travers STOA Gateway.
  4. STOA Gateway vérifie localement la signature et les revendications du JWT à partir des clés JWKS récupérées sur Keycloak et mises en cache.
  5. Une fois le jeton validé localement, STOA Gateway relaie la requête vers http://backend:80 (nginx), qui répond HTTP 200.
control-plane Démarré (hors R1)
Répond 200 sur /health (v1.14.1), mais n’intervient ni dans la déclaration du contrat ni dans le filtrage de la route en R1.
verify.sh Client & Admin
Déclare d’abord le contrat sur POST /admin/contracts de gateway, puis teste GET /apis/quickstart/ping-api/ping (anonyme, invalide, valide).
keycloak Realm quickstart
Émet le jeton client_credentials du client quickstart-caller et expose ses clés publiques JWKS.
gateway Rust 0.9.25
Crée la route publiée (inboundAuth = jwt), vérifie localement le JWT avec le cache JWKS et bloque en 401 ou relaie vers backend.
backend nginx 1.27.5
Service http://backend:80 servant de cible amont ; ne reçoit le trafic que lorsque la passerelle a validé le jeton.

À vous de prédire

Lorsque verify.sh publie le contrat ping-api sur POST /admin/contracts de STOA Gateway avec authorization: Bearer <STOA_ADMIN_API_TOKEN>, que renvoie la passerelle ?

HTTP 202 Accepted en attendant qu’un redémarrage de la passerelle prenne la route en compte.

Pas tout à fait. Non : l’enregistrement du contrat est synchrone et ne nécessite aucun redémarrage du conteneur gateway.

HTTP 201 avec un corps JSON annonçant la clé quickstart:ping-api, 1 route REST créée (routes_generated: 1) et 1 descripteur d’outil généré (tools_generated: 1).

Bonne réponse. Oui : la réponse confirme la création de la route REST /apis/quickstart/ping-api/ping et la génération d’un descripteur d’outil (notons qu’aucun appel MCP n’est exécuté dans cet essai).

HTTP 200 vide, car seul le Control Plane conserve la définition des routes.

Pas tout à fait. Non : c’est bien STOA Gateway qui répond HTTP 201 et retourne le décompte des objets générés.

Révéler la réponse enregistrée

Trace réelle capturée lors de la déclaration du contrat sur STOA Gateway : statut HTTP 201, route REST créée et descripteur d’outil enregistré.

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":1,"status":"ok","tools_generated":1}
Voir la commande exécutée
$ curl -sS --max-time 20 -o /tmp/stoa-quickstart-contract.json -w '%{http_code}' \
>   -X POST "http://127.0.0.1:8872/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"}]}'

Classement

Associez chaque service du quickstart STOA à sa réalité vérifiée dans quickstart/docker-compose.yml :

  1. Compile stoa-gateway en Rust (cargo build --release --locked, sans Pingora ni Kafka), avec téléchargement initial des crates et durée variable selon le cache.
    Voir la réponse

    Service gateway (compilé depuis les sources). À froid, il faut compter le téléchargement de l’image Rust et des dépendances puis la compilation (environ 5 à 15 min selon la machine), contre un build quasi immédiat avec cache chaud.

  2. Télécharge au premier lancement des images verrouillées par digest SHA-256 (PostgreSQL 16.10, Keycloak 26.5.3, Control Plane 1.14.1).
    Voir la réponse

    Services postgres, keycloak et control-plane (images épinglées). Ces images précompilées sont récupérées depuis les registres avec condensat SHA-256 fixe lors d’une première exécution du labo.

  3. Expose l’endpoint POST /admin/contracts protégé par STOA_ADMIN_API_TOKEN qui annonce routes_generated = 1 et tools_generated = 1.
    Voir la réponse

    Service gateway (compilé depuis les sources). C’est stoa-gateway qui reçoit directement la déclaration Bearer envoyée par verify.sh et arme le contrôle JWT sur la route REST.

  4. Écoute sur http://backend:80 avec l’image nginx 1.27.5-alpine épinglée par digest et sert sa page HTML d’accueil quand la passerelle autorise l’appel.
    Voir la réponse

    Service backend (nginx amont). Le service backend du compose minimal est un conteneur nginx standard ciblé par backend_url = http://backend:80.

La règle Dans le quickstart STOA R1, c’est l’appel direct POST /admin/contracts vers STOA Gateway (status: "published", inboundAuth: "jwt") qui crée la route REST protégée ; distinguez aussi le rejeu navigateur 100 % local du labo Docker, dont la durée initiale varie selon le réseau et le cache de compilation.

Détail Expert : payload exact POST /admin/contracts, descripteur MCP non exercé et champ classification

Quatre précisions issues de verify.sh et du code source : (1) POST /admin/contracts s’authentifie par authorization: Bearer $admin_token (lu depuis STOA_ADMIN_API_TOKEN du conteneur gateway) ; (2) le payload utilise tenant_id ("quickstart"), status ("published"), inboundAuth ("jwt") et backend_url ("http://backend:80") ; (3) tools_generated: 1 indique seulement qu’un descripteur d’outil a été dérivé de l’endpoint, sans qu’aucun appel MCP soit testé ; (4) dans stoa-gateway/src/proxy/dynamic.rs, "classification": "H" opère en journalisation souple (soft mode) sans bloquer la requête.

Commande réelle de verify.sh (jeton masqué) et corps JSON exact capturé à la création du contrat quickstart:ping-api.

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":1,"status":"ok","tools_generated":1}
Voir la commande exécutée
$ curl -sS --max-time 20 -o /tmp/stoa-quickstart-contract.json -w '%{http_code}' \
>   -X POST "http://127.0.0.1:8872/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"}]}'

Vérifiez vos acquis

Choisissez une réponse : la correction s’affiche aussitôt.

Quelle affirmation décrit fidèlement la différence entre ce parcours dans le navigateur et une relance du laboratoire Docker ?

Le parcours navigateur interroge Keycloak à distance à chaque clic.

Pas tout à fait. Non : le parcours navigateur rejoue localement les traces enregistrées, sans aucun appel externe pendant le rejeu.

Le parcours navigateur s’exécute localement en 15–20 minutes, tandis qu’un premier labo Docker nécessite le téléchargement d’images/dépendances et une compilation Rust de durée variable selon le cache.

Bonne réponse. Exact : la preuve de référence bénéficiait d’un cache chaud, mais un premier lancement à froid télécharge les images et compile stoa-gateway.

Le contrat POST /admin/contracts teste automatiquement l’exécution d’un client MCP.

Pas tout à fait. Non : la réponse annonce tools_generated = 1, mais seule la route REST /apis/quickstart/ping-api/ping est appelée par verify.sh.

Leçon 2

Prouver le contrôle d’accès : la séquence 401 / 401 / 200 sans rien inventer

Traces réelles capturées le 15 novembre 2026

Claire, DSI Quelles preuves opposables montrent qu’un appel non authentifié ou falsifié n’atteint jamais le service interne ?

Mehdi, chef de projet API Quels résultats attendus dois-je inscrire pour chacun des trois cas de test (sans jeton, jeton invalide, jeton valide) ?

Nadia, architecte sécurité Comment distinguer dans les réponses capturées le rejet produit par STOA Gateway et la réponse issue du service backend ?

Lucas, ingénieur plateforme Quels statuts et corps exacts sont enregistrés sur les trois appels GET /apis/quickstart/ping-api/ping, et pourquoi aucun en-tête WWW-Authenticate n’y figure ?

Une démonstration sérieuse ne se contente pas d’un appel qui réussit : un proxy ouvert par erreur renverrait lui aussi HTTP 200. La preuve minimale repose donc sur trois appels consécutifs vers la même URL. Note importante sur la capture : verify.sh enregistre le code HTTP et le corps de réponse sans capturer les en-têtes HTTP (tels que WWW-Authenticate) ; rejouez ci-dessous les trois traces exactes.

Console · Rejeu de trace enregistrée

Rejouez successivement les trois appels enregistrés sur /apis/quickstart/ping-api/ping :

Sélectionnez chacun des trois scénarios puis cliquez sur « Rejouer la trace » pour observer le statut et le corps capturés sur le banc local.

STOA Gateway (127.0.0.1:8872) · 1. Appel sans en-tête Authorization
Voir la réponse capturée

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 401
{"error":"unauthorized","message":"Missing Authorization header"}

Statut HTTP 401 et corps JSON de la passerelle : {"error":"unauthorized","message":"Missing Authorization header"}. La requête est stoppée avant le service backend.

Voir la commande exécutée
$ curl -sS --max-time 20 -o /tmp/stoa-quickstart-anon.txt -w '%{http_code}' \
>   "http://127.0.0.1:8872/apis/quickstart/ping-api/ping"
STOA Gateway (127.0.0.1:8872) · 2. Appel avec jeton Bearer invalide
Voir la réponse capturée

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 401
{"error":"unauthorized","message":"Invalid token"}

Statut HTTP 401 et corps JSON distinct : {"error":"unauthorized","message":"Invalid token"}. La passerelle rejette localement la chaîne invalide.

Voir la commande exécutée
$ curl -sS --max-time 20 -o /tmp/stoa-quickstart-bad.txt -w '%{http_code}' \
>   "http://127.0.0.1:8872/apis/quickstart/ping-api/ping" \
>   -H "authorization: Bearer invalid"
STOA Gateway (127.0.0.1:8872) · 3. Appel avec jeton Keycloak valide
Voir la réponse capturée

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 200
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

Statut HTTP 200 et corps HTML « Welcome to nginx! » : le JWT étant validé localement via le cache JWKS, la passerelle relaie l’appel vers http://backend:80 (nginx) qui renvoie sa page HTML native.

Voir la commande exécutée
$ curl -sS --max-time 20 -o /tmp/stoa-quickstart-authed.txt -w '%{http_code}' \
>   "http://127.0.0.1:8872/apis/quickstart/ping-api/ping" \
>   -H "authorization: Bearer <ACCESS_TOKEN>"

Repérage dans la trace

Dans le journal complet verify.log du banc quickstart ci-dessous, cliquez sur la ligne précise où la route protégée est déclarée sur la passerelle avant les trois tests d’accès :

Trace du banc local du 15 novembre 2026 (statut et corps)

control plane ok
gateway /health 200
configuring keycloak realm
Logging into http://127.0.0.1:8080 as user quickstart of realm master
Created new realm with id 'quickstart'
Created new client with id '266a90a2-7bbc-46fa-ac0c-bc998a4f8e5c'
POST /admin/contracts 201
GET without token 401
GET with invalid token 401
GET with token 200
VERIFY_OK
Voir la ligne attendue

POST /admin/contracts 201 C’est à cette ligne (POST /admin/contracts 201) que verify.sh déclare la route REST et son exigence JWT sur stoa-gateway.

  • Ces deux premières lignes vérifient seulement que le Control Plane (/health) et le processus stoa-gateway (/health) répondent, avant toute déclaration d’API.
  • Ces lignes préparent le realm quickstart et le client OIDC dans Keycloak ; la route n’existe pas encore sur la passerelle.
  • Ces lignes exécutent la vérification d’accès (401, 401, 200 puis VERIFY_OK) une fois le contrat déjà déclaré.
Voir la commande exécutée
$ bash verification-quickstart/run.sh

La règle Le contrôle d’accès d’une route REST n’est démontré que par le triptyque complet sur la même URL : rejet 401 sans jeton, rejet 401 avec jeton invalide, puis réponse 200 du service backend avec un jeton valide.

Détail Expert : pourquoi le HTTP 200 renvoie du HTML nginx et pourquoi aucun en-tête n’est affiché

Dans quickstart/docker-compose.yml, le service backend exécute l’image officielle nginx:1.27.5-alpine sur http://backend:80 ; recevoir la page HTML « Welcome to nginx! » en HTTP 200 est donc la preuve authentique que la requête a franchi stoa-gateway jusqu’au conteneur amont. Par ailleurs, verify.sh invoque curl avec -sS -o <fichier> -w '%{http_code}' : seuls le code d’état et le corps sont enregistrés, raison pour laquelle aucun en-tête HTTP (comme WWW-Authenticate) ne figure dans les preuves.

Vérifiez vos acquis

Choisissez une réponse : la correction s’affiche aussitôt.

Que prouve le fait d’obtenir deux messages JSON d’erreur en HTTP 401 puis une page HTML « Welcome to nginx! » en HTTP 200 ?

Que nginx a mal interprété le format JSON lors du troisième appel.

Pas tout à fait. Non : le service backend du quickstart est une image nginx standard sur le port 80 qui sert sa page HTML d’accueil dès qu’elle est jointe.

Que les deux premiers appels ont été bloqués par STOA Gateway (réponses JSON de la passerelle) et que seul le troisième a atteint le conteneur nginx backend.

Bonne réponse. Exact : le changement de nature du corps (erreur JSON passerelle en 401, puis HTML nginx amont en 200) matérialise la coupure exercée par la passerelle.

Que Keycloak répond directement en HTML au client lors du troisième appel.

Pas tout à fait. Non : Keycloak délivre un jeton JSON auparavant ; l’appel /apis/quickstart/ping-api/ping traverse STOA Gateway vers http://backend:80.

Pourquoi les sorties de preuve de ce module ne mentionnent-elles pas d’en-tête WWW-Authenticate sur les réponses 401 ?

Parce que le banc de vérification n’a enregistré que les statuts HTTP et les corps de réponse, et qu’aucun en-tête non capturé ne doit être inventé.

Bonne réponse. Exact : la fidélité documentaire impose de s’en tenir strictement aux traces capturées dans verification-quickstart/.

Parce que le protocole HTTP interdit les en-têtes sur un code 401.

Pas tout à fait. Non : HTTP autorise bien sûr les en-têtes sur 401, mais l’outil de capture utilisé ici n’enregistrait que le statut et le corps.

Leçon 3

Validation JWT locale (JWKS), portée du claim tenant_id et limite /health/ready (503)

Traces réelles capturées le 15 novembre 2026

Claire, DSI Que prouve exactement le test sur le jeton Keycloak, qu’est-ce qu’il ne prouve pas encore entre locataires, et pourquoi /health/ready reste-t-elle en 503 ?

Mehdi, chef de projet API Quelles réserves précises (sonde /health/ready en 503, absence de test inter-locataires) doivent figurer dans le bilan de recette ?

Nadia, architecte sécurité Comment stoa-gateway valide-t-elle localement le JWT via JWKS, quelle est la portée exacte du claim tenant_id ici, et d’où vient le 503 sur /health/ready ?

Lucas, ingénieur plateforme Quels protocolMappers Keycloak sont créés par verify.sh, que vérifie le validateur JWT local et pourquoi /health renvoie 200 tandis que /health/ready renvoie 503 ?

STOA Gateway n’interroge pas Keycloak à chaque requête cliente : elle récupère et met en cache les clés publiques JWKS du realm pour vérifier localement la signature, l’émetteur et l’audience. Attention aussi à ne pas surinterpréter la trace : verify.sh ajoute une revendication tenant_id = quickstart dans le jeton, mais ne teste aucun jeton d’un autre locataire — la présence de ce claim ne prouve donc pas à elle seule l’isolation entre locataires.

Remise en ordre

Remettez dans l’ordre exact les quatre opérations réalisées par verify.sh avant d’obtenir VERIFY_OK :

Voir l’ordre vérifié
  1. Vérifier la disponibilité de base du Control Plane (/health → 200) et la sonde de vie de la passerelle (GET /health → 200). Le script s’assure d’abord que les deux processus répondent avant de configurer l’identité et la route.
  2. Créer dans Keycloak le realm quickstart et le client quickstart-caller doté des mappers audience (stoa-mcp-gateway) et tenant_id (quickstart). Ces mappers configurent les revendications portées par le JWT qui sera émis pour ce client d’essai.
  3. Publier directement le contrat ping-api sur POST /admin/contracts de STOA Gateway (HTTP 201) puis vérifier les deux rejets HTTP 401. Le contrat ouvre la route REST protégée et l’on prouve immédiatement le refus sans jeton puis avec jeton invalide.
  4. Demander un jeton client_credentials à Keycloak et appeler GET /apis/quickstart/ping-api/ping pour obtenir HTTP 200 après validation locale par JWKS. La passerelle valide localement la signature et les revendications du JWT grâce aux clés JWKS mises en cache, puis relaie l’appel vers backend.

À vous de prédire

Sur ce même banc où GET /health renvoie 200 et où l’appel API authentifié renvoie 200, que répond la sonde de disponibilité GET /health/ready de STOA Gateway ?

HTTP 200 READY, puisque la route ping-api vient de répondre avec succès.

Pas tout à fait. C’est le piège classique : /health/ready ne teste pas seulement le serveur HTTP, il vérifie aussi l’initialisation du moteur de politiques d’outils MCP.

HTTP 503 avec le corps « NOT READY: tool policy unavailable ».

Bonne réponse. Exact : dans le montage minimal quickstart, policy_boot_tenants n’est pas renseigné ; la sonde readiness reste donc en 503.

HTTP 401 Unauthorized, car /health/ready exige le jeton STOA_ADMIN_API_TOKEN.

Pas tout à fait. Non : les sondes de santé sont interrogeables sans jeton par un orchestrateur.

Révéler la réponse enregistrée

Limite vérifiée du montage minimal : la passerelle sert bien la route REST protégée, mais signale honnêtement en HTTP 503 que ses politiques d’outils initiales ne sont pas chargées.

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 503
NOT READY: tool policy unavailable
Voir la commande exécutée
$ curl -sS --max-time 10 -o response-readiness.txt -w '%{http_code}\n' \
>   "http://127.0.0.1:8872/health/ready"

Classement

Reliez chaque élément technique observé dans l’essai à sa portée exacte :

  1. Vérifie localement la signature avec les clés publiques JWKS mises en cache et contrôle que le jeton cible bien l’audience stoa-mcp-gateway.
    Voir la réponse

    Validation JWT locale (JWKS + aud = stoa-mcp-gateway). La vérification cryptographique et le contrôle d’audience s’effectuent localement dans stoa-gateway sans interroger Keycloak à chaque appel.

  2. Est présente dans le JWT émis par Keycloak, sans que ce quickstart prouve le refus d’un jeton issu d’un autre locataire sur la route.
    Voir la réponse

    Revendication tenant_id = quickstart dans le jeton. Il faut distinguer l’extraction d’un claim présent dans le jeton et la preuve d’isolation multi-locataires sur la route, qui exigerait un test dédié avec un second tenant.

  3. Bloquerait l’envoi de trafic dans Kubernetes si une readinessProbe l’utilisait telle quelle sans configurer les politiques d’outils initiales.
    Voir la réponse

    Sonde GET /health/ready (503 dans le quickstart). Distinguer /health (200, liveness) et /health/ready (503 tant que les politiques d’outils ne sont pas amorcées) évite une indisponibilité immédiate au déploiement.

La règle Tenez-vous strictement à ce que prouve le banc : validation JWT locale via JWKS et audience stoa-mcp-gateway, sonde GET /health/ready encore à HTTP 503 dans le montage minimal, et isolation inter-locataires à tester séparément.

Détail Expert : cache JWKS, distinction forme du jeton vs isolation de route, et cause du 503

Dans verify.sh, le client Keycloak quickstart-caller reçoit deux protocolMappers : oidc-audience-mapper (included.custom.audience = stoa-mcp-gateway) et oidc-hardcoded-claim-mapper (claim.name = tenant_id, claim.value = quickstart). Côté passerelle, la signature RS256 est validée localement grâce au jeu de clés JWKS récupéré sur Keycloak et mis en cache. Comme aucun jeton portant un autre tenant_id n’est soumis à /apis/quickstart/ping-api/ping dans verify.sh, l’essai prouve l’authentification JWT de la route mais pas le cloisonnement multi-locataires. Enfin, GET /health renvoie 200 tandis que GET /health/ready renvoie HTTP 503 NOT READY: tool policy unavailable faute d’amorçage des politiques d’outils MCP.

Interrogation directe de la sonde readiness à l’issue d’un run quickstart réussi.

Trace du banc local du 15 novembre 2026 (statut et corps)

HTTP 503
NOT READY: tool policy unavailable
Voir la commande exécutée
$ curl -sS --max-time 10 -o response-readiness.txt -w '%{http_code}\n' \
>   "http://127.0.0.1:8872/health/ready"

Vérifiez vos acquis

Choisissez une réponse : la correction s’affiche aussitôt.

Que se passerait-il si vous copiez tel quel le montage minimal quickstart dans un cluster Kubernetes utilisant GET /health/ready comme readinessProbe ?

Le pod stoa-gateway serait marqué non prêt (HTTP 503) et le Service Kubernetes ne lui routera aucun trafic tant que les politiques d’outils ne sont pas configurées.

Bonne réponse. Exact : c’est précisément l’intérêt d’avoir vérifié GET /health/ready en plus du scénario 401/401/200.

Kubernetes ignorerait le code 503 puisque GET /health répond 200.

Pas tout à fait. Non : une readinessProbe en 503 retire immédiatement le pod des endpoints actifs.

Keycloak regénérerait automatiquement les politiques manquantes.

Pas tout à fait. Non : Keycloak gère l’identité OIDC, pas le catalogue de politiques d’outils MCP de la passerelle.

Cas de décision

Claire, DSI Le comité vous demande à quelles conditions valider les conclusions de cet essai pour Hélios Distribution. Quelles décisions factuelles retenez-vous simultanément ?

Mehdi, chef de projet API Vous rédigez le procès-verbal de recette du sprint pilote. Quels constats vérifiés cochez-vous ?

Nadia, architecte sécurité Lors de la revue d’architecture, quelles conclusions appuyées sur les preuves du module retenez-vous ?

Lucas, ingénieur plateforme Pour documenter fidèlement ce banc avant d’élargir les tests, quels points vérifiés retenez-vous ?

Plusieurs réponses comptent. Choisissez-les toutes.

Exiger dans la recette automatisée le triptyque complet 401 (sans jeton), 401 (jeton invalide) et 200 (jeton valide vérifié localement via JWKS avec audience stoa-mcp-gateway).

À retenir. Indispensable : c’est la preuve vérifiée que la passerelle filtre effectivement la route REST.

Considérer que le démarrage du Control Plane ou le champ classification = H suffit à bloquer les appels sensibles sans contrat JWT publié sur la passerelle.

À écarter. Sur la route testée, les deux réponses 401 suivent la publication d’un contrat avec inboundAuth = jwt. Le contrat portait aussi classification = H.

Traiter explicitement la sonde GET /health/ready (actuellement en 503 sur le montage minimal) avant tout branchement derrière un orchestrateur.

À retenir. Essentiel : sinon le service sera retiré du routage par la sonde de disponibilité.

Référencer le commit exact testé (639e8b9a2217695cfc2f590e246ed9d4ce4d4913) et noter que ni l’exécution MCP ni l’isolation entre deux locataires ne sont prouvées par ce premier essai.

À retenir. Rigoureux : tools_generated = 1 et la présence d’un claim tenant_id ne remplacent pas des tests dédiés d’appel MCP et de cloisonnement inter-locataires.

Cas de décision

Claire, DSI Un partenaire affirme recevoir HTTP 401 avec « Invalid token » alors que son jeton vient bien de votre Keycloak. Quelle piste technique faites-vous examiner ?

Mehdi, chef de projet API Durant les tests d’intégration, l’appel du partenaire échoue en 401 alors que Keycloak est joignable. Que faites-vous contrôler d’abord ?

Nadia, architecte sécurité Un client OIDC valide dans Keycloak essuie un HTTP 401 sur STOA Gateway. Quels paramètres OIDC vérifiez-vous ?

Lucas, ingénieur plateforme Votre appel Bearer échoue en HTTP 401 malgré une émission réussie sur /protocol/openid-connect/token. Quels points inspectez-vous ?

Une seule réponse tient. Choisissez-la.

Vérifier l’audience du jeton (stoa-mcp-gateway), l’URL d’émetteur OIDC attendue par la passerelle et les revendications produites par les protocolMappers du client Keycloak.

À retenir. Pertinent : l’audience, l’émetteur OIDC et les revendications configurées dans les protocolMappers font partie des contrôles effectués lors de la validation JWT.

Désactiver inboundAuth = jwt sur le contrat pour accélérer la recette.

À écarter. Supprimer le contrôle d’accès masque l’écart de configuration OIDC et annule toute valeur de la recette.

Remplacer le service nginx backend par un autre serveur web en espérant modifier le code 401.

À écarter. Le 401 est renvoyé par STOA Gateway avant tout contact avec le service backend.

La décision de l’équipe

L’équipe valide sur le commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 le filtrage JWT de la route REST par STOA Gateway pour un bac à sable isolé, tout en inscrivant les prérequis suivants avant élargissement : configurer les politiques rendant /health/ready disponible (200), et ajouter des tests dédiés si un second locataire ou des appels MCP entrent au périmètre.

Ce que prouve la trace. Les traces vérifiées démontrent POST /admin/contracts en HTTP 201 (route REST créée et descripteur d’outil généré sans exécution MCP), le double rejet HTTP 401 (sans jeton puis jeton invalide) et le passage HTTP 200 avec jeton Keycloak valide vers le conteneur nginx backend, tout en révélant HTTP 503 sur GET /health/ready (NOT READY: tool policy unavailable).

À retenir

  1. Sur le quickstart STOA vérifié (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), verify.sh envoie directement POST /admin/contracts à STOA Gateway (HTTP 201, authorization: Bearer, status: published, inboundAuth: jwt), ce qui crée la route REST et génère un descripteur d’outil sans exécuter d’appel MCP.
  2. La preuve d’accès repose sur trois traces complémentaires sur la même URL : HTTP 401 sans jeton, HTTP 401 avec jeton invalide (corps JSON passerelle), puis HTTP 200 après validation JWT locale par cache JWKS (corps HTML du service nginx backend) — sans toutefois tester l’isolation face à un autre locataire.
  3. Le parcours navigateur s’exécute en 15–20 min sans aucun appel externe pendant le rejeu, tandis qu’un premier labo Docker télécharge images/crates avec un temps de build variable et laisse GET /health/ready en HTTP 503 (NOT READY: tool policy unavailable).

À reproduire sur votre poste (Docker local)

Reproduire la pile quickstart dans un dossier neuf avec tools/run-lab.sh

Relancer depuis la racine de ce projet une exécution isolée du quickstart au commit vérifié 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 via le wrapper portable tools/run-lab.sh, qui isole les fichiers temporaires, le tag d’image passerelle et vos preuves personnelles dans un dossier neuf sans jamais modifier verification-quickstart/ ni references/.

Prérequis
Docker Compose v2 actif et accès réseau (images + crates Rust au premier build) · Ports boucle locale 127.0.0.1:8870, 8871 et 8872 libres · Durée de build variable (5 à 15 min à froid selon machine/réseau, ~1 min avec cache chaud)
Durée estimée
Build variable + ~1 min de vérification

Commande et guide de vérification locale

bash tools/run-lab.sh --prepare-only --out .lab-test/preparation
bash tools/run-lab.sh --out .lab-test/essai-1
cat .lab-test/essai-1/verify.log
cat .lab-test/essai-1/readiness-status.txt .lab-test/essai-1/response-readiness.txt

Wrapper basé sur verification-quickstart/run.sh (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), isolant les 4 fichiers temporaires de verify.sh et le tag passerelle dans un projet dédié stoa-lab-learner-* avec délais *_TIMEOUT strictement positifs.

  1. Depuis la racine du projet stoa-formations, testez d’abord à blanc la préparation d’un dossier neuf (aucun appel Docker : vérifie le commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 propre et la syntaxe du runner adapté) :
    bash tools/run-lab.sh --prepare-only --out .lab-test/preparation
  2. Lancez ensuite l’exécution réelle dans un nouveau dossier personnel (vérifie que les ports 127.0.0.1:8870–8872 sont libres, crée un projet Compose dédié stoa-lab-learner-* et compile/démarre la pile) :
    bash tools/run-lab.sh --out .lab-test/essai-1
  3. Contrôlez dans votre dossier personnel le journal verify.log (201 / 401 / 401 / 200 -> VERIFY_OK) ainsi que le statut 503 de /health/ready :
    cat .lab-test/essai-1/verify.log
    cat .lab-test/essai-1/readiness-status.txt .lab-test/essai-1/response-readiness.txt
  4. Vérifiez qu’aucun conteneur du projet éphémère stoa-lab-learner-* ne subsiste après le nettoyage borné de fin d’exécution (fichier vide attendu, sans suppression des volumes ou images hors projet dédié) :
    cat .lab-test/essai-1/remaining-containers.txt

Vous avez réussi si .lab-test/essai-1/verify.log se termine par VERIFY_OK, response-anon.txt et response-bad.txt contiennent les deux erreurs JSON 401, response-authed.txt contient le HTML nginx, response-readiness.txt affiche NOT READY: tool policy unavailable (503), remaining-containers.txt est vide et verification-quickstart/ est demeuré 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 systématiquement les deux preuves négatives (sans jeton et jeton invalide) en plus du cas nominal lors des démonstrations fournisseurs ou internes ?
  • Avons-nous arbitré en équipe notre mode de livraison de la passerelle (compilation maîtrisée en CI ou image précompilée) selon nos contraintes d’exploitation ?
  • Nos critères d’acceptation du pilote distinguent-ils clairement sonde de vie (/health) et sonde de disponibilité (/health/ready) ?
  • Avons-nous séparé dans nos jalons la validation d’une route REST mono-locataire des preuves supplémentaires requises pour MCP et le multi-locataires ?

Mehdi, chef de projet API

  • Nos tickets de recette API décrivent-ils explicitement les trois appels 401 / 401 / 200 et les corps attendus ?
  • Avons-nous séparé dans le planning le temps d’appropriation locale sans appel externe pendant le rejeu (15–20 min) et la durée variable de préparation d’un banc Docker ?
  • Les équipes consommatrices connaissent-elles l’audience OIDC et les revendications exactes à demander à l’équipe IAM ?
  • Les limites non couvertes par un premier essai (sonde /health/ready en 503, absence de test inter-locataires et d’appel MCP) sont-elles tracées au journal projet ?

Nadia, architecte sécurité

  • Notre fournisseur OIDC d’entreprise émet-il une revendication d’audience dédiée à la passerelle vérifiable localement avec les clés JWKS ?
  • Comment gérons-nous aujourd’hui l’écart entre le Control Plane et la déclaration directe des contrats publiés sur la passerelle ?
  • Quels tests complémentaires avec un second locataire prévoyons-nous avant d’affirmer qu’une route est isolée par tenant ?
  • Quelle stratégie d’amorçage des politiques d’outils retenons-nous avant d’activer une readinessProbe sur /health/ready ?

Lucas, ingénieur plateforme

  • Utilisons-nous un wrapper isolé (comme tools/run-lab.sh) qui vérifie les ports 127.0.0.1 libres et confine le nettoyage au seul projet Compose d’essai ?
  • Nos tests automatisés vérifient-ils que le corps d’erreur 401 provient bien de la passerelle et non du service backend ?
  • Les mappers Keycloak (audience stoa-mcp-gateway et revendications attendues) sont-ils versionnés en code plutôt que saisis à la main ?
  • Surveillons-nous séparément /health et /health/ready dans nos manifestes de déploiement ?

Fin du module 1

Vous disposez d’une base vérifiée sur le contrôle d’accès STOA

Vous avez parcouru le premier module en accès libre : déclaration directe du contrat sur STOA Gateway, rejeu local du triptyque 401 / 401 / 200, validation JWT locale par cache JWKS et limites exactes du montage minimal (/health/ready en 503, absence d’appel MCP et de preuve inter-locataires).

  • Distinguer le service Control Plane démarré et la déclaration effective du contrat JWT (POST /admin/contracts) envoyée directement à STOA Gateway.
  • Interpréter la triple preuve d’accès (401 anonyme, 401 jeton invalide, 200 jeton Keycloak valide vérifié localement par JWKS) à partir des statuts et corps capturés.
  • Distinguer la validation de forme et des revendications du jeton (aud = stoa-mcp-gateway, présence de tenant_id) d’une preuve d’isolation entre locataires ou d’exécution MCP.
  • Consigner le HTTP 503 de /health/ready dans le montage minimal du quickstart.

Pour aller plus loin

Poursuivez au module 2 sur les politiques d’outils MCP et la sonde /health/ready. En parcours Expert, bash tools/run-lab.sh relance le quickstart Docker dans un nouveau dossier de laboratoire.