Chapter 24 — Token exchange and delegation

Practice (60 min)

1. Stand up Keycloak (or ory/hydra + a small exchange shim) configured for token exchange. Register bff, orders-api, catalog-api, payments-api as clients/audiences.
2. Write orders-api so it: validates the incoming token's aud, then calls the STS to exchange for aud=catalog-api (scope price:read) and aud=payments-api (scope charge:create), each exp ~60s.
3. Prove: a token minted for catalog-api is rejected by payments-api (aud check). Remove the aud check from payments-api and show the replay now works — then put it back.
4. Add the act chain; log it at every hop; reconstruct the delegation chain from logs for one request.
5. Implement the phantom token pattern at a gateway (opaque token in, introspect, forward JWT).
6. Combine with Ch 23: require mTLS/SPIFFE for the connection and a valid audience-scoped token for the request.

Build it in Go (45 min) — signed tokens, verified properly, and token exchange

This lab mints and verifies compact JWTs with Ed25519 using only the standard library, so every check a JWT library should make is visible. It also implements a token-exchange endpoint: the orders service trades the user's token for a narrower, shorter-lived token for the payments API, recording itself as the actor.

// tokens: signed tokens done carefully, and token exchange (RFC 8693).
//
// A JWT is three base64url parts: header.claims.signature. This lab builds
// and verifies them with Ed25519 using only the standard library, then shows
// the checks that real-world token bugs skip: a PINNED algorithm, issuer,
// audience, expiry -- and a token-exchange service that turns a user's token
// for the "orders" API into a narrower, shorter-lived token for "payments".
//
//	go run ./tokens
package main

import (
	"crypto/ed25519"
	"crypto/rand"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"slices"
	"strings"
	"time"
)

type claims struct {
	Iss   string   `json:"iss"`
	Sub   string   `json:"sub"`
	Aud   string   `json:"aud"`
	Exp   int64    `json:"exp"`
	Iat   int64    `json:"iat"`
	Scope []string `json:"scope"`
	Act   *actor   `json:"act,omitempty"` // who is acting on the subject's behalf
}

type actor struct {
	Sub string `json:"sub"`
}

var b64 = base64.RawURLEncoding

type issuer struct {
	name string
	kid  string
	priv ed25519.PrivateKey
}

func (is issuer) mint(c claims) string {
	c.Iss = is.name
	c.Iat = time.Now().Unix()
	h, _ := json.Marshal(map[string]string{"alg": "EdDSA", "typ": "JWT", "kid": is.kid})
	p, _ := json.Marshal(c)
	signing := b64.EncodeToString(h) + "." + b64.EncodeToString(p)
	return signing + "." + b64.EncodeToString(ed25519.Sign(is.priv, []byte(signing)))
}

// verifier holds the trusted keys by kid and the checks for ONE audience.
type verifier struct {
	keys     map[string]ed25519.PublicKey // from the issuer's JWKS, fetched and cached
	issuer   string
	audience string
}

func (v verifier) verify(tok string) (*claims, error) {
	parts := strings.Split(tok, ".")
	if len(parts) != 3 {
		return nil, errors.New("malformed token")
	}
	var hdr struct{ Alg, Kid string }
	hb, err := b64.DecodeString(parts[0])
	if err != nil || json.Unmarshal(hb, &hdr) != nil {
		return nil, errors.New("bad header")
	}
	// 1. PIN the algorithm. Never let the token choose it ("alg":"none",
	//    or RS256->HS256 confusion are the classic forgeries).
	if hdr.Alg != "EdDSA" {
		return nil, fmt.Errorf("algorithm %q not allowed", hdr.Alg)
	}
	key, ok := v.keys[hdr.Kid]
	if !ok {
		return nil, fmt.Errorf("unknown key id %q", hdr.Kid)
	}
	sig, err := b64.DecodeString(parts[2])
	if err != nil || !ed25519.Verify(key, []byte(parts[0]+"."+parts[1]), sig) {
		return nil, errors.New("bad signature")
	}
	// 2. Only now trust the claims.
	var c claims
	pb, _ := b64.DecodeString(parts[1])
	if err := json.Unmarshal(pb, &c); err != nil {
		return nil, errors.New("bad claims")
	}
	now := time.Now().Unix()
	switch {
	case c.Iss != v.issuer:
		return nil, fmt.Errorf("wrong issuer %q", c.Iss)
	case c.Aud != v.audience: // a token for "orders" must not work at "payments"
		return nil, fmt.Errorf("token is for %q, not %q", c.Aud, v.audience)
	case now >= c.Exp+30: // 30 s leeway for clock skew
		return nil, errors.New("expired")
	}
	return &c, nil
}

// exchange is a token-exchange endpoint: it accepts a valid token for the
// caller's own API and issues a DOWNSCOPED token for one downstream API.
func exchange(is issuer, subjectTok string, actorID, target string, wantScope []string) (string, error) {
	in, err := verifier{keys: map[string]ed25519.PublicKey{is.kid: is.priv.Public().(ed25519.PublicKey)},
		issuer: is.name, audience: "orders"}.verify(subjectTok)
	if err != nil {
		return "", fmt.Errorf("subject token rejected: %w", err)
	}
	var scope []string
	for _, s := range wantScope { // never MORE than the user had
		if slices.Contains(in.Scope, s) {
			scope = append(scope, s)
		}
	}
	exp := min(in.Exp, time.Now().Add(2*time.Minute).Unix()) // never LONGER than the original
	return is.mint(claims{Sub: in.Sub, Aud: target, Exp: exp, Scope: scope, Act: &actor{actorID}}), nil
}

func main() {
	pub, priv, _ := ed25519.GenerateKey(rand.Reader)
	idp := issuer{"https://id.shop.example", "key-2026-10", priv}
	keys := map[string]ed25519.PublicKey{idp.kid: pub}
	ordersAPI := verifier{keys, idp.name, "orders"}
	paymentsAPI := verifier{keys, idp.name, "payments"}

	userTok := idp.mint(claims{Sub: "user-42", Aud: "orders", Exp: time.Now().Add(15 * time.Minute).Unix(),
		Scope: []string{"orders:write", "payments:charge", "profile:read"}})
	try := func(label string, v verifier, tok string) {
		c, err := v.verify(tok)
		if err != nil {
			fmt.Printf("%-46s REJECT  %v\n", label, err)
			return
		}
		act := ""
		if c.Act != nil {
			act = " act=" + c.Act.Sub
		}
		fmt.Printf("%-46s ACCEPT  sub=%s aud=%s scope=%v ttl=%ds%s\n", label, c.Sub, c.Aud, c.Scope, c.Exp-time.Now().Unix(), act)
	}

	try("user token at orders", ordersAPI, userTok)
	try("same token replayed at payments", paymentsAPI, userTok)

	// Forgery 1: "alg":"none" with no signature.
	h := b64.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`))
	p := strings.Split(userTok, ".")[1]
	try(`forged "alg":"none"`, ordersAPI, h+"."+p+".")

	// Forgery 2: edit the claims (escalate to admin), keep the old signature.
	var c claims
	pb, _ := b64.DecodeString(p)
	json.Unmarshal(pb, &c)
	c.Scope = append(c.Scope, "admin")
	pj, _ := json.Marshal(c)
	parts := strings.Split(userTok, ".")
	try("claims edited, old signature", ordersAPI, parts[0]+"."+b64.EncodeToString(pj)+"."+parts[2])

	try("expired token", ordersAPI, idp.mint(claims{Sub: "user-42", Aud: "orders", Exp: time.Now().Add(-time.Hour).Unix()}))

	// Token exchange: the orders service calls payments ON BEHALF of user-42.
	down, err := exchange(idp, userTok, "spiffe://shop.example/ns/prod/sa/orders", "payments",
		[]string{"payments:charge", "payments:refund"})
	if err != nil {
		fmt.Println(err)
		return
	}
	try("exchanged token at payments", paymentsAPI, down)
	try("exchanged token replayed at orders", ordersAPI, down)
}

$ go run ./tokens
user token at orders                           ACCEPT  sub=user-42 aud=orders scope=[orders:write payments:charge profile:read] ttl=900s
same token replayed at payments                REJECT  token is for "orders", not "payments"
forged "alg":"none"                            REJECT  algorithm "none" not allowed
claims edited, old signature                   REJECT  bad signature
expired token                                  REJECT  expired
exchanged token at payments                    ACCEPT  sub=user-42 aud=payments scope=[payments:charge] ttl=120s act=spiffe://shop.example/ns/prod/sa/orders
exchanged token replayed at orders             REJECT  token is for "payments", not "orders"

What to notice:

• The audience check stops lateral replay. Without it, any service that receives a user's token can use it against every other service, which turns one compromised service into all of them (Chapter 3's lateral movement).
• The algorithm is pinned by the verifier, never read from the token. The "alg":"none" and RS256→HS256 confusion forgeries both depend on the verifier trusting the header.
• The exchange narrowed everything. The caller asked for payments:charge and payments:refund, got only payments:charge (the user never had refund), and the lifetime fell from 15 minutes to 2. The act claim keeps the delegation visible in payments' audit log.
• Verify the signature before parsing claims you act on. The code decodes the header first (only to choose the key), then verifies, and only then trusts the claims.

Exercises:

1. Add kid rotation: publish two public keys, mint with the new one, and keep accepting the old one until its tokens expire.
2. Add OIDC ID-token checks (Chapter 39): nonce must match the login request, and azp must be your client ID.
3. Add a jti claim and a replay cache for one-time tokens (password reset, email verification).