JWT token exchange — OIDC IdP + agentgateway STS, hop by hop

The cast

The walkthrough

What each field in the JWT means

Why it matters

Three properties fall out of this design that you don't get with a plain bearer-token-forwarded-everywhere approach:

• Short-lived — every hop mints a fresh token with a 10-minute TTL. A stolen token rots quickly.
• Single-purpose — every token is pinned to one audience. tool-mcp won't accept a planner-bound token. The orchestrator can't replay Alice's subject token anywhere except where the IdP said it could.
• Signed lineage — the act chain encodes who walked the request through. A sensitive resource can demand "the immediate caller is the planner, and the chain shows orchestrator and then alice at the root" — and the gateway checks it as CEL on the inbound token. No out-of-band trust needed.

Negative tests

The walkthrough above is the happy path. The protocol is only as good as the rejections, so the cases below are the ones worth running explicitly when you stand up an STS-fronted setup. They all come down to the same idea: the chain is signed, audience-pinned and short-lived, so any attempt to skip a hop, widen scope or replay a token should be visibly rejected by either the STS or the receiving gateway. Curl examples below use the same hostnames as the walkthrough.

Prereq — mint the subject tokens. Cases 1–3 and 5 need a valid IdP-style subject token plus a tampered variant. Run the shared Mint your own test JWTs helper once and source tokens.env — that gives you $VALID_JWT, $TAMPERED_JWT, $EXPIRED_JWT and $WRONG_AUD_JWT. Configure the STS so the orchestrator client's allowed subject audience is api.example.com (what the helper signs) and trusted issuer is https://test-idp.example.com. Cases 4, 6 and 7 reference tokens the STS itself produces ($HOP1_TOKEN, $EXPIRED_HOP2_TOKEN, $HOP2_FROM_PREVIOUS_KEY) — those come from the walkthrough's exchange calls, not from the mint script.

Case 1 — STS rejects an invalid subject_token

Orchestrator tries to exchange a token whose signature does not verify (use $TAMPERED_JWT), whose exp is in the past ($EXPIRED_JWT), or whose aud is not what the orchestrator client is configured to accept ($WRONG_AUD_JWT). The STS refuses to mint anything.

curl -i -X POST https://agw-sts.example.com/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$TAMPERED_JWT \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
  -d audience=planner \
  -d client_id=orchestrator \
  -d client_secret=$ORCH_SECRET
# HTTP/1.1 400 Bad Request
# {"error":"invalid_grant","error_description":"subject_token verification failed"}

Case 2 — STS refuses to widen the audience

Orchestrator presents a valid subject token ($VALID_JWT) and asks for a token bound to a service it is not registered to call (aud=billing). Even though the subject token is valid, the STS rejects because the calling client is not permitted to obtain a token for that audience.

curl -i -X POST https://agw-sts.example.com/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$VALID_JWT \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
  -d audience=billing \
  -d client_id=orchestrator \
  -d client_secret=$ORCH_SECRET
# HTTP/1.1 403 Forbidden
# {"error":"invalid_target","error_description":"client not permitted for requested audience"}

Case 3 — STS will not widen scope

Subject token carries scope=invoke.orchestrator (the helper sets this by default on $VALID_JWT). Orchestrator asks the STS for scope="invoke.planner admin.planner". The STS may downscope (return narrower or equivalent scope), but it must not hand out a scope the subject was not authorised for.

curl -s -X POST https://agw-sts.example.com/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$VALID_JWT \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
  -d audience=planner \
  -d scope="invoke.planner admin.planner" \
  -d client_id=orchestrator \
  -d client_secret=$ORCH_SECRET \
  | jq -r .scope
# "invoke.planner"

Case 4 — tool-mcp rejects a token without the expected act chain

Skip the second exchange. Try to call tool-mcp directly with the hop-1 token (the one issued to orchestrator with aud=planner). The gateway in front of tool-mcp runs the CEL listed under step 7 of the walkthrough, sees that aud != tool-mcp and that act.act.sub is missing, and rejects.

curl -i -H "Authorization: Bearer $HOP1_TOKEN" \
  https://tool-mcp.example.com/mcp
# HTTP/1.1 403 Forbidden
# response body: Audiences in Jwt are not allowed

Case 5 — tool-mcp rejects a blind pass-through of Alice's subject token

The strongest negative case in the whole picture. An attacker who somehow obtains Alice's original subject token ($VALID_JWT here) tries to use it directly against tool-mcp. The token is signed by the IdP (not the STS), its aud is api.example.com not tool-mcp, and it carries no act claim. The receiving gateway rejects on every count.

curl -i -H "Authorization: Bearer $VALID_JWT" \
  https://tool-mcp.example.com/mcp
# HTTP/1.1 401 Unauthorized
# response body: Jwt issuer is not configured  (STS-only trust)

Keep this case in your evidence pack: it proves the exchange isn't decoration. Without going through the STS, there is no token that tool-mcp will accept.

Case 6 — receiving gateway rejects on expired hop-2 token

Hop-2 tokens carry a 10-minute TTL. Hold one for 11 minutes and replay it. The gateway in front of tool-mcp rejects on the exp check, even though every other claim still matches.

curl -i -H "Authorization: Bearer $EXPIRED_HOP2_TOKEN" \
  https://tool-mcp.example.com/mcp
# HTTP/1.1 401 Unauthorized
# response body: Jwt is expired

Case 7 — replay-after-rotation

Rotate the STS signing key. Tokens minted under the previous key remain syntactically valid but their signature no longer verifies against the new JWKS. Replay one and the receiving gateway rejects.

curl -i -H "Authorization: Bearer $HOP2_FROM_PREVIOUS_KEY" \
  https://tool-mcp.example.com/mcp
# HTTP/1.1 401 Unauthorized
# response body: Jwt verification fails

This is the case to run when you want to demonstrate the blast-radius story: a leaked private key, once rotated out, can no longer mint anything that the system will accept on the next fetch of the JWKS.

What to log. Every rejection above should produce an STS audit record (or, for cases 4–7, a receiving-gateway access log) containing the calling client, requested audience and scope, the error code, and the jti of the token. The token contents themselves must not appear in the log. Together those entries are the auditor's view of why a request was rejected without ever leaking a credential.