ADR-039: Token rotation and bootstrap flows

Category: architecture Provenance: human

Decision

Automatic token rotation with grace periods for zero-downtime updates. Bootstrap flows enable initial token creation without manual intervention. Tokens rotated 7 days before expiry with dual-token support during transition.

Rationale

Token rotation is security best practice. Long-lived tokens increase compromise risk. Automatic rotation 7 days before expiry prevents service disruptions. Grace period with dual tokens ensures zero downtime - old token works while clients migrate to new token. Bootstrap flows enable automated initial setup without manual token distribution. Prometheus metrics provide visibility into rotation health. Version tracking enables audit trail of token changes.

Agent Instructions

Token rotation implemented in src/keycloak_operator/handlers/token_rotation.py. Daily timer checks tokens expiring within 7 days and rotates them. Rotated secrets contain both new token (token) and old token (token-previous) during grace period. Hourly cleanup removes old tokens after grace period expires. Bootstrap flows in tests/integration/test_token_bootstrap.py. Rotation tracked via Prometheus metrics. Tokens have version numbers that increment on rotation. Use SecretManager from src/keycloak_operator/utils/secret_manager.py for rotation operations.

Rejected Alternatives

Non-rotatable tokens

Security risk. Compromised tokens can't be invalidated without recreating all resources.

Manual token distribution only

Doesn't scale. Error-prone. Slows down initial setup and emergency rotation.