README
¶
09: Key Rotation with Grace Periods
Non-UI · No infrastructure needed · Builds on Example 02
KidStore + CompositeKeyLookup keep the old signing key valid for a
configurable window after rotation, so in-flight tokens don't get
broken when an admin rotates an app's key.
Two-process architecture
main.go boots:
- An auth server that exposes
POST /apps/{id}/rotate— drives the rotation. - A resource server whose middleware uses
CompositeKeyLookup{KeyStore, KidStore}so tokens signed with the just-rotated-out key keep validating until the grace period expires.
Quick start
make demo # interactive walkthrough
make serve # auth :8081, resource :8082
# Drive rotation by hand
curl -X POST http://localhost:8081/apps/<client_id>/rotate
The grace period in this demo is 100 ms — long enough to demonstrate both states, short enough not to slow the demo down. Real deployments use hours or days.
See WALKTHROUGH.md for the full step-by-step.
Targets
make … |
What |
|---|---|
demo (default) |
Walkthrough with TUI renderer |
demo-plain |
Plain renderer |
demo-ci |
Non-interactive |
serve |
Bind AS + RS on real ports |
walkthrough |
Regenerate WALKTHROUGH.md |
What's next
10 — Security — algorithm confusion (CVE-2015-9235), cross-app token forgery, JWKS leak prevention.
Documentation
¶
Overview ¶
Example 09: Key Rotation with Grace Periods.
In production, signing keys must be rotated periodically without breaking tokens that were issued with the old key. OneAuth uses `KidStore` + `CompositeKeyLookup` to keep the old key valid for a grace window after rotation.
Two-process architecture:
make serve # auth :8081 (registration + rotation), resource :8082 make demo # walkthrough that drives rotation in-process
In --serve mode an admin can drive rotation by hand:
POST /apps/dcr → returns client_id + client_secret (kv1)
POST /apps/{id}/rotate → returns new client_secret (kv2),
old key sticks in KidStore for grace period
GET /resource (Bearer token) → validates against KeyStore + KidStore
See: https://www.rfc-editor.org/rfc/rfc7517 (JWK)
Source Files