Stop Writing Auth: Delegate to Keycloak

Requirements

What must be true — the how is yours.

1. R1 Protected endpoints accept only tokens issued by your realm, with the signature verified against the provider's keys.
2. R2 Authorization is enforced from claims: a valid token without the required role is refused. rehearsed by D3
3. R3 An expired or tampered token is refused with a 401, never a 500 and never a stack trace. rehearsed by D1 · D2
4. R4 The service survives a realm key rotation without a restart and without a window of blanket rejection. rehearsed by D4

Technical guidance

• ▸Fetch the signing keys from the provider's JWKS endpoint; never paste a key.
• ▸Validate issuer, audience and expiry — a valid signature alone proves little.
• ▸Cache JWKS or you make a network call per request; cache it wrong and a rotation locks everybody out.

Definition of done

All of them, or it isn't shipped.

• ○ 401, a log line, and no stack trace in the response. — not recorded yet D1
• ○ 401 for the expired token, and a freshly issued one still works immediately. — not recorded yet D2
• ○ 403, not 401 — authenticated, not authorised, and the log says which. — not recorded yet D3
• ○ The service fetches the new key and accepts the token without a restart; tokens still valid under the old key keep working until they expire. — not recorded yet D4
• ○ docker compose up brings the realm and the API up together, with the realm imported rather than clicked in by hand. — not recorded yet

nothing recorded yet — running the drills fills these in