a. Overview

Until now anyone could create or delete events in the catalog. BoxOffice needs to know who is calling (authentication) and what they may do (authorization) — and it should not ask every service to solve that problem again. The standard answer is an API gateway¹: the single front door for the API, where tokens are validated once and requests are routed to the right service. Behind it, services trust the identity the gateway passes along.

This lab builds chapter 5 of the story of the course: the front door that stateless replicas need, where the token is checked once for every service and no replica keeps a session. It implements the API gateway of class 4, the service map of class 5 and the token validation at the gateway of the identity page.

Before you start

docker compose version        # Docker Compose v2.x (or newer)
java -version                 # 21 or newer
mvn -v                        # Apache Maven 3.9+
k6 version                    # k6 v1.0+
uv --version                  # uv (runs the Python helper scripts)

Start state — the end of lab 3:

📁 boxoffice/
├──  docker-compose.yaml        # db, catalog-1..3, edge
├──  infra/nginx/nginx.conf     # edge -> catalog replicas
├── 📁 load/  hello.js smoke.js load.js stress.js ratelimit.js
├── 📁 results/ ...
├── 📁 scripts/ ...
└── 📁 services/catalog/          # with InstanceHeaderFilter

Slides

Click the slides and use ← → to move through them; F goes full screen and P opens the presenter view, with the notes. Open the slides in a new tab

What you will build

sequenceDiagram
    autonumber
    actor Fan
    participant E as edge :80
    participant G as gateway :8080
    participant A as auth :8081
    participant C as catalog-1..3 :8082
    Fan->>E: POST /auth/login {email, password}
    E->>G: forward
    G->>A: route /auth/** (open)
    A->>A: BCrypt check, sign JWT with private key
    A-->>Fan: 200 {accessToken: "eyJ..."}
    Fan->>E: POST /catalog/events + Authorization: Bearer eyJ...
    E->>G: forward
    G->>A: GET /auth/.well-known/jwks.json (first time only, then cached)
    G->>G: verify signature, exp, iss, aud — scope "admin"?
    G->>C: route lb://catalog + X-User-Id, X-User-Scope
    C-->>Fan: 201 Created

Tokens are JWTs²: signed JSON that any holder of the public key can verify without calling auth.

The topology after this lab: edge (Nginx: TLS termination in production, rate limiting, load balancing over gateway replicas) → gateway (identity, routing, load balancing over service instances) → services.

Steps

3. Try it end to end

With both steps done, rebuild and start everything:

docker compose up --build -d
docker compose ps        # db, catalog-1..3, auth, gateway healthy; edge running

Now as the administrator (created at startup from ADMIN_EMAIL/ADMIN_PASSWORD):

ADMIN=$(curl -s -X POST localhost/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"admin@boxoffice.dev","password":"boxoffice-admin"}' | jq -r .accessToken)

curl -s -X PUT localhost/catalog/events/2 -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' \
  -d '{"title":"Match #2 (rescheduled)","category":"SPORTS","venueId":15,"startsAt":"2027-03-02T21:00:00-03:00","priceFrom":100}' | jq .title

# look inside the token: header and claims are only Base64URL, NOT encrypted
echo "$ADMIN" | jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

Try the other failure cases too: an expired token (JWT_TTL=PT30S docker compose up -d auth, log in again, wait two minutes — the gateway tolerates 60 s of clock skew past exp — then docker compose up -d auth to go back to one hour), a token with one character changed (signature check fails), and restarting auth (new key pair: old tokens are rejected because their kid no longer exists in the JWKS — see the warning in step 1).

Measure it: the price of a front door

Every hop and every check costs something. Send the same request, GET /catalog/events/{id}, at the same rate along four paths — straight to one catalog replica, to the gateway port, through the edge, and through the edge with a token the gateway validates — so that each difference isolates one cost; then measure the throughput of auth itself.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// Lab 4: what do the edge, the gateway and the token check cost? The same request,
// GET /catalog/events/{id}, at the same arrival rate along four paths:
//   service   straight to one catalog replica              (no edge, no gateway)
//   direct    to the gateway port                          (gateway → catalog)
//   open      through the edge                             (edge → gateway → catalog)
//   jwt       through the edge with a valid token          (the gateway also validates the JWT)
// Catalog replicas publish no port, so k6 runs inside the compose network (see the lab page):
//   docker run --rm -i --network boxoffice_default -v "$PWD":/w -w /w grafana/k6 run -e RATE=50 load/gateway.js
import http from 'k6/http';
import { check } from 'k6';

const EDGE = __ENV.BASE_URL || 'http://edge';
const GATEWAY = __ENV.GATEWAY_URL || 'http://gateway:8080';
const SERVICE = __ENV.SERVICE_URL || 'http://catalog-1:8082';
const RATE = Number(__ENV.RATE || 50);

const scenario = (exec) => ({
  executor: 'constant-arrival-rate', exec, rate: RATE, timeUnit: '1s', duration: '1m',
  preAllocatedVUs: 50, maxVUs: 500,
});

export const options = {
  scenarios: { service: scenario('service'), direct: scenario('direct'), open: scenario('open'), jwt: scenario('jwt') },
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
  thresholds: {
    'http_req_duration{scenario:service}': ['p(99)<500'],
    'http_req_duration{scenario:direct}': ['p(99)<500'],
    'http_req_duration{scenario:open}': ['p(99)<500'],
    'http_req_duration{scenario:jwt}': ['p(99)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

// runs once: register a fan and log in; every VU reuses the token
export function setup() {
  const email = `fan-${Date.now()}@boxoffice.dev`;
  const json = { headers: { 'Content-Type': 'application/json' } };
  http.post(`${EDGE}/auth/register`, JSON.stringify({ name: 'Load Fan', email, password: 'secret-123' }), json);
  const login = http.post(`${EDGE}/auth/login`, JSON.stringify({ email, password: 'secret-123' }), json);
  check(login, { 'login is 200': (r) => r.status === 200 });
  return { token: login.json('accessToken') };
}

const randomId = () => 1 + Math.floor(Math.random() * 200000);
const event = (base) => `${base}/catalog/events/${randomId()}`;

export function service() {
  check(http.get(event(SERVICE)), { 'service is 200': (r) => r.status === 200 });
}

export function direct() {
  check(http.get(event(GATEWAY)), { 'direct is 200': (r) => r.status === 200 });
}

export function open() {
  check(http.get(event(EDGE)), { 'open is 200': (r) => r.status === 200 });
}

// an open route, but a request that carries a token gets it validated (a bad one is rejected with 401)
export function jwt(data) {
  const res = http.get(event(EDGE), { headers: { Authorization: `Bearer ${data.token}` } });
  check(res, { 'jwt is 200': (r) => r.status === 200 });
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Lab 4: how many logins per second can auth take? BCrypt is slow on purpose.
//   k6 run -e RATE=20 load/login.js
import http from 'k6/http';
import { check } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'http://localhost';
const RATE = Number(__ENV.RATE || 20);
const json = { headers: { 'Content-Type': 'application/json' } };

export const options = {
  scenarios: {
    logins: {
      executor: 'constant-arrival-rate', rate: RATE, timeUnit: '1s', duration: '30s',
      preAllocatedVUs: 20, maxVUs: 300,
    },
  },
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
  thresholds: { http_req_failed: ['rate<0.01'], 'http_req_duration{name:login}': ['p(99)<1000'] },
};

export function setup() {
  const email = `login-${Date.now()}@boxoffice.dev`;
  http.post(`${BASE_URL}/auth/register`, JSON.stringify({ name: 'Login Fan', email, password: 'secret-123' }), json);
  return { email };
}

export default function (data) {
  const res = http.post(`${BASE_URL}/auth/login`,
    JSON.stringify({ email: data.email, password: 'secret-123' }), { ...json, tags: { name: 'login' } });
  check(res, { 'login is 200': (r) => r.status === 200 });
}

# k6 inside the compose network: the catalog replicas publish no port
k6net() { docker run --rm -i --network boxoffice_default -v "$PWD":/w -w /w grafana/k6 "$@"; }
k6net run -q -e RATE=50 load/gateway.js > /dev/null   # warm-up: right after a build the JVMs are cold
k6net run -e RATE=50 load/gateway.js                  # 4 paths × 50 req/s
mkdir -p results/lab4
for r in 5 10 20 40; do k6 run -q -e RATE=$r --summary-export results/lab4/rate-$r.json load/login.js; done
uv run scripts/summarize.py results/lab4/rate-*.json

Record in results/lab4.md:

# Lab 4 — gateway and identity

## Hops (50 req/s each, 1 min)
| Path | p50 (ms) | p95 (ms) | p99 (ms) |
|---|---:|---:|---:|
| catalog alone (service) | | | |
| gateway → catalog (direct) | | | |
| edge → gateway → catalog (open) | | | |
| edge → gateway (JWT validated) → catalog (jwt) | | | |

At p50: gateway hop = direct − service ≈ ____ ms; edge hop = open − direct ≈ ____ ms; JWT validation = jwt − open ≈ ____ ms.

## Login capacity
<table from summarize.py: rate, p50, p99, errors>
- Max logins/s with p99 < 1 s: ____ ; CPU of auth at that rate (docker stats): ____ %
- One BCrypt check (cost 10) takes about ____ ms on my machine.

## Questions
- Why does the gateway validate tokens locally instead of calling auth on every request?
- What would happen to the flash sale if every request called /auth/login?

How to read it:

• Each scenario is named after its path in k6's summary (http_req_duration{scenario:service} …). Every path adds one piece to the previous one, so the differences are the costs: the gateway hop and the edge hop each add a fraction of a millisecond to a few milliseconds at p50 (an extra network hop and a proxy). Signature checking with RS256 is microseconds of CPU: JWT validation is cheap because it is local — the gateway fetched the public key once and never calls auth per request — so jwt and open are within noise of each other. The catalog route is open, but a request that carries a token still has it validated: a tampered one gets 401 there too.
• Login is expensive on purpose. BCrypt with cost 10 burns tens of milliseconds of CPU per attempt, so auth with 1 CPU tops out at roughly ten to twenty logins per second (in a run for this lab, 10 logins/s kept p99 under 200 ms with auth at ~80% CPU, and 20 logins/s overloaded it). Past the ceiling it does not degrade gently: the logins share the CPU, all of them slow down, and once they exceed the gateway's 5 s response-timeout they fail with 504 — most of them, at 20 logins/s. That is exactly what makes password guessing slow — and why clients must reuse tokens instead of logging in per request. During a flash sale, logins should happen before 10:00.

Troubleshooting

Clean up

docker compose down          # keeps the database (users and events)
# docker compose down -v     # resets everything: users are created again from scratch

Keep everything: lab 5 adds Redis to this stack.

Deliverable

• services/auth and services/gateway running; the new infra/nginx/nginx.conf sends everything to the gateway.
• The curl session above reproduced: 201, 200, 401, 403, and an admin update that works.
• The spoofing test: sending X-User-Id yourself has no effect (show the evidence).
• results/lab4.md with the hop table, the login capacity and the two answers.
• Repository tagged lab4; quiz answered.

End state

📁 boxoffice/
├──  docker-compose.yaml        # replaced: + auth (8081), + gateway (8080); edge -> gateway
├──  infra/nginx/nginx.conf     # replaced: everything goes to the gateway, /actuator hidden
├──  load/gateway.js  load/login.js           # new
├── 📁 services/auth/             # new: users, BCrypt, RS256 JWT, JWKS
├── 📁 services/gateway/          # new: routes, lb://catalog, JWT validation, identity headers
└──  results/lab4.md  results/lab4/

Next: Lab 5 — Caching.