STOA Learn

Training · Controlling API Access with STOA

Module 1 of 2 · Free access

Decide whether a first API route can be opened to a partner

First Protected API: Filter Access and Scope a Pilot

Objective. On the tested route, compare the two rejections for a missing or invalid token and the backend response for a valid token.

View the verified details

First Protected API: Contract, 401/401/200 Proof, and Quickstart Limits. Read the recorded responses on GET /apis/quickstart/ping-api/ping after declaring the contract on STOA Gateway. The route returns HTTP 401 without a token, HTTP 401 with an invalid token and HTTP 200 with a valid Keycloak JWT. In this setup, /health/ready returns HTTP 503.

Module guide · Quick guide

Your goal in this module (15 to 20 min)

Evaluate on a concrete case whether opening a first partner API route properly protects your internal service. Pick your role at the top: the Decision-maker path needs zero commands or setup, while the Expert path shows exact commands.

Excerpt from the recorded trace Local quickstart · Tested route: missing or invalid JWT, HTTP 401. Valid JWT, HTTP 200.
View the verified details

How to go through this module in 15 to 20 minutes

Pick the business role closest to yours at the top of the page: role prompts adapt while every technical fact and recorded trace stays identical.

Switch anytime between the Decision-maker path (zero commands, focused on architecture, evidence, and boundaries) and the Expert path (exact curl commands, source-level notes, and local wrapper tools/run-lab.sh).

Every terminal output in this module is an identified local replay of files captured during real verification of the STOA quickstart: zero external calls are made during replay.

The case · fictional company

Helios Distribution opens a logistics check endpoint to a first pilot carrier

Helios Distribution is preparing a logistics API route for a pilot carrier. The team checks how this route responds to different token inputs.

View the verified details

Helios Distribution runs an internal inventory catalogue and wants to expose a first REST route to a pilot freight partner before later evaluating MCP tool exposure.

The platform team ran the STOA quickstart with Control Plane, STOA Gateway, Keycloak, PostgreSQL and nginx. They sent three requests to the same pilot route, with a missing, invalid and valid token.

Before approving a pilot, engineering leadership requires reproducible proof of rejections and forwarding pinned to an exact commit, alongside a rigorous statement of what the bench proves and what remains untested.

Around the table, each stakeholder asks the question of their role.

  • Claire, CIO What do the three responses on the pilot route show, and what checks should we record before expanding the pilot?
  • Mehdi, API Project Lead Which verifiable acceptance criteria belong in the test ticket while separating fast local trace replay from variable Docker build time?
  • Nadia, Security Architect Which script actually declares the route on the gateway, how is the JWT signature verified with JWKS, and why does /health/ready return 503?
  • Lucas, Platform Engineer What exact payload hits stoa-gateway, what bodies return on 201/401/200/503, and how do we run a clean lab via tools/run-lab.sh without touching reference proofs?

Fictional company. The case illustrates a realistic API exposure project; only the outputs captured during verified runs on the local STOA benches count as evidence (status codes and bodies reproduced untouched).

Your view

“As soon as the STOA Control Plane service starts in the quickstart, it automatically declares and protects the API route on the gateway with JWT authentication.”

Rather agree

Needs nuance. That is a common assumption around a control plane, yet quickstart/docker-compose.yml explicitly notes (R1) that the Control Plane runs without declaring or protecting the route on the gateway.

Rather disagree

The trial backs you up. Spot on: in the verified quickstart, verify.sh posts a contract directly to POST /admin/contracts on STOA Gateway (with status: "published" and inboundAuth: "jwt") to create the dynamic REST route and activate JWT filtering.

See what the trial shows

On the verified quickstart bench (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), verify.sh calls POST /admin/contracts directly on stoa-gateway with authorization: Bearer <STOA_ADMIN_API_TOKEN>: the HTTP 201 response reports routes_generated = 1 and tools_generated = 1 for key quickstart:ping-api (only the REST route is subsequently tested).

Lesson 1

Declaring the Contract Directly on STOA Gateway

Real traces captured on 15 November 2026

Claire, CIO Which component validates the token on the pilot route and how does the lab activate this check?

Mehdi, API Project Lead Which action creates the protected REST endpoint we are accepting?

Nadia, Security Architect What is each container’s actual role when opening the route in quickstart R1?

Lucas, Platform Engineer What does POST /admin/contracts sent by verify.sh to stoa-gateway return, and how are the five containers assembled?

In the STOA quickstart stack, five services run on an isolated Docker network: postgres, control-plane, keycloak, gateway, and an upstream nginx container named backend. Pay close attention to which actor sends the administrative request that creates the route in R1.

Actual chain executed by verify.sh in the STOA quickstart
Actual chain executed by verify.sh in the STOA quickstartFive-step diagram: control-plane running off the declaration path, direct contract declaration by verify.sh to gateway, Keycloak token issuance, GET /ping call, local validation via cached JWKS, and forwarding to backend.1. /admin2. Token3. GET /ping4. JWKS cache5. :80control-planeRunning (unused R1)verify.shClient & Adminkeycloakquickstart realmgatewayRust 0.9.25backendnginx 1.27.5
  1. verify.sh sends POST /admin/contracts directly to STOA Gateway (tenant_id: quickstart, status: published, inboundAuth: jwt, backend_url: http://backend:80), while control-plane stays off this R1 path.
  2. verify.sh requests an access token from Keycloak’s quickstart realm via client_credentials.
  3. verify.sh calls GET /apis/quickstart/ping-api/ping through STOA Gateway.
  4. STOA Gateway verifies the JWT signature and claims locally using the JWKS public keys fetched from Keycloak and cached in memory.
  5. Once validated locally, STOA Gateway forwards the request to http://backend:80 (nginx), which returns HTTP 200.
control-plane Running (unused R1)
Returns 200 on /health (v1.14.1), but neither declares the contract nor enforces route auth in R1.
verify.sh Client & Admin
Posts the contract directly to POST /admin/contracts on gateway, then tests GET /apis/quickstart/ping-api/ping (anon, invalid, valid).
keycloak quickstart realm
Issues the client_credentials token for quickstart-caller and serves its public JWKS keys.
gateway Rust 0.9.25
Creates the published route (inboundAuth = jwt), validates JWTs locally using cached JWKS, and rejects with 401 or relays to backend.
backend nginx 1.27.5
Upstream http://backend:80 target; only receives traffic after the gateway validates the JWT locally.

Your prediction

When verify.sh posts the ping-api contract to POST /admin/contracts on STOA Gateway with authorization: Bearer <STOA_ADMIN_API_TOKEN>, what does the gateway return?

HTTP 202 Accepted while waiting for a gateway container restart to load the route.

Not quite. No: contract registration is synchronous and requires no container restart.

HTTP 201 with a JSON body reporting key quickstart:ping-api, 1 created REST route (routes_generated: 1), and 1 generated tool descriptor (tools_generated: 1).

Correct. Yes: the response reports creation of REST route /apis/quickstart/ping-api/ping and generation of a tool descriptor (note that no MCP call is executed in this test).

An empty HTTP 200, because route definitions live exclusively inside the Control Plane.

Not quite. No: STOA Gateway itself responds with HTTP 201 and returns the generated object counts.

Reveal the recorded answer

Real trace captured when declaring the contract on STOA Gateway: HTTP 201 status, created REST route, and generated tool descriptor.

Local bench trace from 15 November 2026 (status and body)

HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":1,"status":"ok","tools_generated":1}
See the executed command
$ 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"}]}'

Classifying

Match each quickstart service to its verified configuration in quickstart/docker-compose.yml:

  1. Compiles stoa-gateway in Rust (cargo build --release --locked, without Pingora or Kafka), pulling crates on a cold build with variable duration depending on cache.
    See the answer

    gateway service (compiled from source). Cold runs pull the Rust builder image and crates before compiling (roughly 5 to 15 min depending on machine/network), whereas warm cache reruns finish much faster.

  2. Pulls container images locked by SHA-256 digest on first lab launch (PostgreSQL 16.10, Keycloak 26.5.3, Control Plane 1.14.1).
    See the answer

    postgres, keycloak, and control-plane (digest-pinned images). Those prebuilt images are downloaded by immutable SHA-256 digest when setting up the Docker lab for the first time.

  3. Exposes endpoint POST /admin/contracts protected by STOA_ADMIN_API_TOKEN, reporting routes_generated = 1 and tools_generated = 1.
    See the answer

    gateway service (compiled from source). stoa-gateway receives verify.sh’s direct Bearer declaration and arms JWT filtering on the REST route.

  4. Listens on http://backend:80 using digest-pinned nginx 1.27.5-alpine and returns its default HTML welcome page once the gateway allows the call.
    See the answer

    backend service (upstream nginx). The minimal compose stack names this upstream service backend and points backend_url to http://backend:80.

The rule In quickstart R1, verify.sh’s direct POST /admin/contracts call to STOA Gateway (status: "published", inboundAuth: "jwt") is what creates the protected REST route; also separate 100% local browser replay from the Docker lab, whose initial build time varies with network and cache.

Expert Deep Dive: exact POST /admin/contracts payload, untested MCP descriptor, and classification

Four source-level precisions from verify.sh and stoa-gateway: (1) POST /admin/contracts authenticates via authorization: Bearer $admin_token (read from STOA_ADMIN_API_TOKEN in the gateway container); (2) the payload uses tenant_id ("quickstart"), status ("published"), inboundAuth ("jwt"), and backend_url ("http://backend:80"); (3) tools_generated: 1 only indicates that a tool descriptor was derived from the endpoint — no MCP call is executed; (4) in stoa-gateway/src/proxy/dynamic.rs, "classification": "H" runs in log-only soft mode without blocking requests.

Exact verify.sh administrative command (token masked) and JSON body captured when creating contract quickstart:ping-api.

Local bench trace from 15 November 2026 (status and body)

HTTP 201
{"key":"quickstart:ping-api","llm_capabilities":0,"routes_generated":1,"status":"ok","tools_generated":1}
See the executed command
$ 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"}]}'

Check what you have learned

Pick an answer: the correction appears at once.

Which statement accurately contrasts this in-browser course with re-running the Docker lab?

The browser course queries Keycloak over the network whenever you replay a trace.

Not quite. No: the browser course replays recorded traces locally with zero external calls during replay.

The browser course runs locally in 15–20 minutes, whereas a first Docker lab run requires pulling images/crates and a Rust compile whose duration varies with cache.

Correct. Correct: the stored reference proof used a warm cache, while a cold run downloads base images/dependencies and compiles stoa-gateway.

POST /admin/contracts automatically proves end-to-end MCP client execution.

Not quite. No: the response reports tools_generated = 1, but verify.sh only exercises the REST route /apis/quickstart/ping-api/ping.

Lesson 2

Proving Access Control: The 401 / 401 / 200 Sequence Without Inventing Anything

Real traces captured on 15 November 2026

Claire, CIO What auditable evidence proves an unauthenticated or forged call never reaches our internal service?

Mehdi, API Project Lead What expected results belong on each of the three test cases (missing token, invalid token, valid token)?

Nadia, Security Architect How do the captured payloads distinguish a rejection produced by STOA Gateway from a response produced by the backend service?

Lucas, Platform Engineer What exact status codes and bodies are recorded across the three GET /apis/quickstart/ping-api/ping calls, and why is no WWW-Authenticate header shown?

A credible security demo never stops at a single HTTP 200: an accidentally open proxy would return 200 too. Minimal proof requires three consecutive calls to the exact same URL. Important capture note: verify.sh saves the HTTP status code and response body without recording HTTP headers (such as WWW-Authenticate); replay the three exact traces below.

Console · Recorded trace replay

Replay the three recorded calls to /apis/quickstart/ping-api/ping in order:

Select each scenario and click “Replay trace” to inspect the exact status code and body captured on the local bench.

STOA Gateway (127.0.0.1:8872) · 1. Call without Authorization header
View captured response

Local bench trace from 15 November 2026 (status and body)

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

HTTP 401 status and gateway JSON body: {"error":"unauthorized","message":"Missing Authorization header"}. Stopped before the backend service.

See the executed command
$ 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. Call with invalid Bearer token
View captured response

Local bench trace from 15 November 2026 (status and body)

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

HTTP 401 status and distinct JSON body: {"error":"unauthorized","message":"Invalid token"}. Rejected locally by the gateway.

See the executed command
$ 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. Call with valid Keycloak token
View captured response

Local bench trace from 15 November 2026 (status and body)

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>

HTTP 200 status and HTML body “Welcome to nginx!”: once the JWT passes local verification via cached JWKS, the gateway forwards the request to http://backend:80 (nginx), which serves its default HTML page.

See the executed command
$ 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>"

Spotting in the trace

In the complete verify.log output from the quickstart bench below, click the exact line where the protected route is declared on the gateway right before the three access tests:

Local bench trace from 15 November 2026 (status and body)

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
See the target line

POST /admin/contracts 201 Line 7 (POST /admin/contracts 201) is where verify.sh declares the REST route and its JWT policy on stoa-gateway.

  • Those first two lines only confirm Control Plane (/health) and stoa-gateway (/health) liveness before any API contract is declared.
  • Those lines configure the quickstart realm and OIDC client in Keycloak; no route exists on the gateway yet.
  • Those lines run the access-control checks (401, 401, 200, then VERIFY_OK) after the contract has already been declared.
See the executed command
$ bash verification-quickstart/run.sh

The rule REST route access control is only proved by the full three-call sequence on the same URL: 401 without token, 401 with an invalid token, and 200 from the upstream backend service with a valid token.

Expert Deep Dive: why HTTP 200 returns nginx HTML and why no headers are shown

In quickstart/docker-compose.yml, the backend service runs official image nginx:1.27.5-alpine on http://backend:80; receiving the “Welcome to nginx!” HTML page on HTTP 200 is therefore genuine proof that the request traversed stoa-gateway to the upstream container. Furthermore, verify.sh invokes curl with -sS -o <file> -w '%{http_code}': only the status code and body are written to disk, which is why no HTTP headers (such as WWW-Authenticate) appear in the proof files.

Check what you have learned

Pick an answer: the correction appears at once.

What does getting two JSON error bodies on HTTP 401 followed by a “Welcome to nginx!” HTML page on HTTP 200 prove?

That nginx misparsed JSON on the third request.

Not quite. No: the quickstart backend service is a standard nginx container on port 80 that serves its HTML welcome page whenever reached.

That the first two requests were stopped by STOA Gateway (gateway JSON errors) and only the third reached the upstream nginx backend container.

Correct. Correct: switching from gateway JSON error bodies on 401 to upstream nginx HTML on 200 proves where enforcement happened.

That Keycloak answered the client directly in HTML on the third call.

Not quite. No: Keycloak issues a JSON token beforehand; /apis/quickstart/ping-api/ping flows through STOA Gateway to http://backend:80.

Why do the proof outputs in this module omit WWW-Authenticate headers on 401 responses?

Because the verification bench recorded only HTTP status codes and response bodies, and unrecorded headers must never be invented.

Correct. Correct: strict evidentiary fidelity means showing only what verification-quickstart/ actually captured.

Because the HTTP specification forbids headers on status 401.

Not quite. No: HTTP permits headers on 401, but the curl capture command recorded status code and body only.

Lesson 3

Local JWT Validation (JWKS), Scope of tenant_id, and the /health/ready (503) Limit

Real traces captured on 15 November 2026

Claire, CIO What exactly does the test prove on the Keycloak token, what remains unproved across tenants, and why does /health/ready still return 503?

Mehdi, API Project Lead Which explicit caveats (/health/ready at 503, absence of cross-tenant test) belong in the acceptance summary?

Nadia, Security Architect How does stoa-gateway validate JWTs locally via JWKS, what is the exact scope of the tenant_id claim here, and what causes 503 on /health/ready?

Lucas, Platform Engineer Which Keycloak protocolMappers are created by verify.sh, what does the local JWT validator check, and why does /health return 200 while /health/ready returns 503?

STOA Gateway does not query Keycloak on every incoming API call: it fetches and caches the realm’s public JWKS keys to verify the signature, issuer, and audience locally. Be equally careful not to overread the trace: verify.sh adds claim tenant_id = quickstart to the token, yet never tests a token from another tenant — the presence of that claim alone therefore does not prove cross-tenant route isolation.

Ordering

Place the four operations executed by verify.sh before printing VERIFY_OK in their exact order:

See the verified order
  1. Check Control Plane health (/health → 200) and gateway liveness (GET /health → 200). The script first confirms both processes respond before configuring identity or routes.
  2. Create realm quickstart and client quickstart-caller in Keycloak with audience (stoa-mcp-gateway) and tenant_id (quickstart) mappers. Those mappers configure the claims carried inside the JWT issued for this test client.
  3. Publish contract ping-api directly on POST /admin/contracts of STOA Gateway (HTTP 201) and verify both HTTP 401 rejections. Publishing the contract opens the protected REST route and immediately proves rejection with missing and invalid tokens.
  4. Request a client_credentials token from Keycloak and call GET /apis/quickstart/ping-api/ping to obtain HTTP 200 after local JWKS validation. The gateway verifies the JWT signature and claims locally against cached JWKS keys, then forwards the call to backend.

Your prediction

On the exact same bench where GET /health returns 200 and the authenticated API call returns 200, what does STOA Gateway’s readiness probe GET /health/ready return?

HTTP 200 READY, since the ping-api route just succeeded.

Not quite. Classic pitfall: /health/ready checks more than the HTTP listener — it also checks whether MCP tool policies have been initialised.

HTTP 503 with body “NOT READY: tool policy unavailable”.

Correct. Correct: policy_boot_tenants is unset in the minimal quickstart stack, so readiness stays at 503.

HTTP 401 Unauthorized, because /health/ready requires STOA_ADMIN_API_TOKEN.

Not quite. No: health probes are queried unauthenticated by orchestrators.

Reveal the recorded answer

Verified boundary of the minimal setup: the gateway serves the protected REST route properly, yet honestly reports HTTP 503 because initial tool policies are not bootstrapped.

Local bench trace from 15 November 2026 (status and body)

HTTP 503
NOT READY: tool policy unavailable
See the executed command
$ curl -sS --max-time 10 -o response-readiness.txt -w '%{http_code}\n' \
>   "http://127.0.0.1:8872/health/ready"

Classifying

Match each technical element observed in the run to what it actually establishes:

  1. Verifies the cryptographic signature locally with cached JWKS keys and checks that the token targets audience stoa-mcp-gateway.
    See the answer

    Local JWT validation (JWKS + aud = stoa-mcp-gateway). Signature verification and audience checking run locally inside stoa-gateway without calling Keycloak per request.

  2. Appears inside the Keycloak-issued JWT, without this quickstart proving rejection of a token belonging to another tenant on the route.
    See the answer

    Claim tenant_id = quickstart inside the token. Separate extracting a claim from a token and proving cross-tenant route authorization, which requires a dedicated multi-tenant test.

  3. Would stop Kubernetes from routing traffic if used as-is in a readinessProbe without bootstrapping initial tool policies.
    See the answer

    Probe GET /health/ready (503 in quickstart). Separating /health (200, liveness) from /health/ready (503 until tool policies load) avoids an immediate rollout outage.

The rule Stick strictly to what the bench proves: local JWT validation via cached JWKS and audience stoa-mcp-gateway, GET /health/ready still returning HTTP 503 in the minimal stack, and cross-tenant isolation requiring separate testing.

Expert Deep Dive: JWKS cache, token shape vs route isolation, and cause of 503

In verify.sh, Keycloak client quickstart-caller is created with two protocolMappers: oidc-audience-mapper (included.custom.audience = stoa-mcp-gateway) and oidc-hardcoded-claim-mapper (claim.name = tenant_id, claim.value = quickstart). On the gateway side, RS256 signatures are verified locally against the JWKS keyset fetched from Keycloak and cached in memory. Because verify.sh never sends a token carrying a different tenant_id to /apis/quickstart/ping-api/ping, this run proves JWT authentication on the route rather than cross-tenant isolation. Finally, GET /health returns 200 while GET /health/ready returns HTTP 503 NOT READY: tool policy unavailable without MCP tool-policy bootstrap.

Direct readiness probe check right after a passing quickstart run.

Local bench trace from 15 November 2026 (status and body)

HTTP 503
NOT READY: tool policy unavailable
See the executed command
$ curl -sS --max-time 10 -o response-readiness.txt -w '%{http_code}\n' \
>   "http://127.0.0.1:8872/health/ready"

Check what you have learned

Pick an answer: the correction appears at once.

What would happen if you lifted the minimal quickstart configuration straight into Kubernetes with GET /health/ready wired as readinessProbe?

The stoa-gateway pod would stay NotReady (HTTP 503) and the Kubernetes Service would route zero traffic to it until tool policies are configured.

Correct. Correct: checking GET /health/ready alongside the 401/401/200 sequence catches this before deployment.

Kubernetes would ignore the 503 status because GET /health returns 200.

Not quite. No: a failing readinessProbe immediately removes the pod from active Service endpoints.

Keycloak would automatically generate the missing tool policies.

Not quite. No: Keycloak manages OIDC identity, not the gateway’s MCP tool-policy store.

Decision case

Claire, CIO Leadership asks under which conditions you endorse the conclusions of Helios Distribution’s bench run. Which factual decisions do you keep together?

Mehdi, API Project Lead You are writing the acceptance record for the pilot sprint. Which verified findings do you tick?

Nadia, Security Architect During architecture review, which evidence-backed conclusions do you keep from this module?

Lucas, Platform Engineer To document this bench accurately before expanding test coverage, which verified points do you keep?

Several answers count. Pick them all.

Require the full automated 401 (no token), 401 (invalid token), and 200 (valid token verified locally via JWKS with audience stoa-mcp-gateway) sequence in acceptance tests.

Worth keeping. Essential: only the full triplet proves active gateway filtering on the REST route.

Assume starting the Control Plane or setting classification = H is enough to block sensitive calls without a published JWT contract on the gateway.

To set aside. The tested route returns the two 401 responses after a contract with inboundAuth = jwt is published. The contract also carried classification = H.

Address GET /health/ready explicitly (currently 503 in the minimal stack) before wiring an orchestrator readiness probe.

Worth keeping. Critical: otherwise the orchestrator will withhold traffic from the gateway.

Record the exact verified commit (639e8b9a2217695cfc2f590e246ed9d4ce4d4913) and state that neither MCP tool execution nor cross-tenant isolation is proved by this first run.

Worth keeping. Sound engineering hygiene: tools_generated = 1 and a tenant_id claim in a single-tenant token do not replace dedicated MCP and multi-tenant tests.

Decision case

Claire, CIO A pilot partner reports HTTP 401 “Invalid token” even though their token came from your Keycloak instance. Which technical check do you ask for?

Mehdi, API Project Lead During integration testing, the partner’s call fails with 401 while Keycloak is healthy. What do you have the team check?

Nadia, Security Architect A valid OIDC client in Keycloak hits HTTP 401 on STOA Gateway. Which OIDC parameters do you inspect?

Lucas, Platform Engineer Your Bearer call fails with HTTP 401 right after /protocol/openid-connect/token succeeds. Which points do you check?

One answer only holds. Pick it.

Check the token audience (stoa-mcp-gateway), the OIDC issuer URL expected by the gateway, and the claims configured on the Keycloak client’s protocolMappers.

Worth keeping. Relevant check: audience, OIDC issuer URL, and protocolMapper claims are verified during local JWT validation.

Disable inboundAuth = jwt on the contract to unblock acceptance testing.

To set aside. Removing access control hides the OIDC mismatch and invalidates the security proof.

Swap the nginx backend container for another web server hoping to clear the 401.

To set aside. HTTP 401 is returned by STOA Gateway before any upstream connection to backend.

The decision of the team

The team validates JWT filtering on the REST route on STOA Gateway at commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 for an isolated sandbox pilot, while recording clear prerequisites before wider rollout: bootstrapping tool policies so /health/ready returns 200, and running dedicated tests if a second tenant or MCP calls enter scope.

What the trace proves. Verified traces demonstrate POST /admin/contracts returning HTTP 201 (REST route created and tool descriptor generated without MCP execution), dual HTTP 401 rejections (missing token and invalid token), and HTTP 200 forwarding with a valid Keycloak token to the nginx backend container, while surfacing HTTP 503 on GET /health/ready (NOT READY: tool policy unavailable).

Key points

  1. On the verified STOA quickstart (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), verify.sh sends POST /admin/contracts directly to STOA Gateway (HTTP 201, authorization: Bearer, status: published, inboundAuth: jwt), creating the REST route and generating a tool descriptor without running any MCP call.
  2. Access-control proof rests on three complementary traces on the same URL: HTTP 401 without token, HTTP 401 with invalid token (gateway JSON bodies), and HTTP 200 after local JWT verification via cached JWKS (HTML body from the upstream nginx backend) — without testing cross-tenant isolation.
  3. The browser course runs in 15–20 min with zero external calls during replay, whereas a first Docker lab run pulls images/crates with variable build time and leaves GET /health/ready at HTTP 503 (NOT READY: tool policy unavailable).

Reproduce on your machine (local Docker)

Reproduce the Quickstart Stack in a Fresh Folder with tools/run-lab.sh

Run an isolated reproduction of the quickstart at verified commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 from the root of this project using portable wrapper tools/run-lab.sh, isolating temporary files, the gateway image tag, and your personal proofs in a brand-new folder without ever touching verification-quickstart/ or references/.

Prerequisites
Docker Compose v2 running + network access (base images & Rust crates on first build) · Loopback ports 127.0.0.1:8870, 8871, and 8872 free · Variable build duration (roughly 5 to 15 min cold depending on hardware/network, ~1 min with warm cache)
Estimated time
Variable build + ~1 min verification

Local verification script & checklist

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 built around verification-quickstart/run.sh (commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913), isolating verify.sh’s 4 temp files and gateway image tag inside a dedicated stoa-lab-learner-* project with strictly positive *_TIMEOUT bounds.

  1. From the root of stoa-formations, run a zero-Docker dry check first to prepare a fresh directory (verifies clean commit 639e8b9a2217695cfc2f590e246ed9d4ce4d4913 and adapted runner syntax):
    bash tools/run-lab.sh --prepare-only --out .lab-test/preparation
  2. Launch the live isolated run into a brand-new personal directory (checks that 127.0.0.1:8870–8872 are free, allocates a dedicated stoa-lab-learner-* Compose project, and builds/starts the stack):
    bash tools/run-lab.sh --out .lab-test/essai-1
  3. Inspect verify.log (201 / 401 / 401 / 200 -> VERIFY_OK) and the 503 /health/ready files inside your personal output directory:
    cat .lab-test/essai-1/verify.log
    cat .lab-test/essai-1/readiness-status.txt .lab-test/essai-1/response-readiness.txt
  4. Confirm no ephemeral stoa-lab-learner-* container remains after the bounded exit cleanup (empty file expected, without removing volumes or images outside the dedicated project):
    cat .lab-test/essai-1/remaining-containers.txt

You have succeeded if .lab-test/essai-1/verify.log ends with VERIFY_OK, response-anon.txt and response-bad.txt hold the two 401 JSON errors, response-authed.txt holds the nginx HTML page, response-readiness.txt shows NOT READY: tool policy unavailable (503), remaining-containers.txt is empty, and verification-quickstart/ remains untouched.

Apply

What about you?

Ask yourself these questions about your own organisation. Your ticks and notes are neither sent nor stored: print them or copy them.

Claire, CIO

  • Do we systematically require both negative proofs (missing token and invalid token) alongside the happy path during vendor or internal demos?
  • Have we agreed as a team on our gateway delivery workflow (controlled CI source build or prebuilt image) given our operational constraints?
  • Do our staging sign-off gates explicitly distinguish liveness (/health) from readiness (/health/ready)?
  • Have we separated single-tenant REST validation from the additional tests needed before claiming MCP execution or multi-tenant isolation?

Mehdi, API Project Lead

  • Do our API acceptance tickets spell out all three 401 / 401 / 200 calls and their expected response payloads?
  • Does our sprint plan separate local reading with zero external calls during replay (15–20 min) from variable Docker bench build time?
  • Do consuming teams know the OIDC audience and claims to request from IAM?
  • Are boundaries not covered by this initial run (/health/ready returning 503, no cross-tenant test, no MCP call) logged in the project register?

Nadia, Security Architect

  • Does our enterprise OIDC provider emit a gateway-specific audience claim verified locally via cached JWKS keys?
  • How do we currently handle the gap between Control Plane state and contracts declared directly on the gateway?
  • Which negative tests with a second tenant will we run before claiming route-level tenant isolation?
  • What tool-policy bootstrap strategy will we put in place before enabling a Kubernetes readinessProbe on /health/ready?

Lucas, Platform Engineer

  • Do we use an isolated wrapper (such as tools/run-lab.sh) that checks free 127.0.0.1 ports and scopes cleanup strictly to a dedicated Compose project?
  • Do our automated checks assert that 401 error JSON comes from the gateway rather than the upstream backend service?
  • Are our Keycloak mappers (stoa-mcp-gateway audience and required claims) version-controlled rather than clicked manually?
  • Do our deployment manifests monitor /health and /health/ready separately?

End of module 1

You Now Have a Verified Baseline on STOA Access Control

You have completed the free opening module: direct contract declaration on STOA Gateway, local replay of the 401 / 401 / 200 sequence, local JWT validation via cached JWKS, and the exact boundaries of the minimal setup (/health/ready at 503, no MCP call, and no cross-tenant isolation proof).

  • Distinguish a running Control Plane service from directly declaring an active JWT contract (POST /admin/contracts) on STOA Gateway.
  • Read the three-step access proof (401 anonymous, 401 invalid token, 200 valid Keycloak token verified locally via cached JWKS) strictly from captured status codes and bodies.
  • Separate JWT structure and claim validation (aud = stoa-mcp-gateway, presence of tenant_id) from unverified MCP execution or cross-tenant isolation claims.
  • Record the HTTP 503 response from /health/ready in the minimal quickstart setup.

Where to go next

Continue to Module 2 on MCP tool policies and the /health/ready probe. On the Expert path, bash tools/run-lab.sh reproduces the Docker quickstart in a fresh lab directory.