gameplane / docs
SECURITY

Credential Rotation

Rotate identity, database, registry, backup, signing, webhook, and mTLS material without breaking access or recovery.

Users & Accessv0.218 MIN
Preserve recovery dependencies before rotation

Do not destroy a backup or signing key until retained recovery points and verification requirements are resolved.

Inventory dependencies

Map every credential, consumer, Secret, owner, expiry, overlap capability, revocation path, and audit requirement.

Include OIDC, recovery users, service tokens, DB, registry, and backupCatalog all authentication providers, service accounts, and storage credentials.
Include signing keys, webhook tokens, TLS, CAs, and agent mTLSAccount for all material used in secure channels and artifact verification.
Record downstream consumers and emergency restoration ownershipDocument every system that depends on each credential and who owns recovery.

Categories to inventory

  • Identity & access: OIDC provider secrets (in gameplane-auth-* Secrets), local admin passwords (stored as argon2id hashes), recovery user tokens, and session keys.
  • Database: PostgreSQL connection credentials (if not using managed auth), backup database credentials, and replication user tokens.
  • Container registries: Docker/OCI registry pull secrets (for module images, game server containers, and custom Gameplane builds), and push credentials for your own registry.
  • Backup destinations: S3 / cloud storage access keys, webhook tokens for backup notifications, and backup repository encryption passphrases.
  • Signing & verification: Cosign signing keys (for module and image signatures), cert-manager issuers and their backing secrets.
  • mTLS & webhooks: API-to-agent mTLS client certificates, webhook authentication tokens, and TLS termination certificates for ingress.

Rotate with overlap

Issue and distribute the new material, validate every consumer, then revoke the old material.

Use dual-key or dual-CA trust windows where supportedAccept both old and new credentials simultaneously during the transition period.
Stage database and registry rotations to preserve connectivityUpdate credentials in a sequence that ensures continuous access (e.g., update consumer first, then issuer).
Watch auth, reconciliation, backups, sources, webhooks, expiry, and auditMonitor all systems that depend on the rotated credential for errors or delays.

Safe rotation sequence

  1. Generate the new material using the credential provider’s native tooling (e.g., kubectl create secret for Secrets, cert-manager for TLS, OIDC provider for tokens).
  2. Distribute to all consumers — update Kubernetes Secrets, environment variables, config files, and ingress TLS certificate references.
  3. Validate every consumer — test authentication, API calls, backup uploads, module signing, and webhook delivery. Monitor logs for errors.
  4. Revoke the old material only after you have confirmed:
    • No live requests are using the old credential.
    • Backups have been taken with the new credential and verified readable.
    • Audit logs show the new credential in use.
    • Recovery and retention requirements are met (e.g., old signing keys may be kept offline for recovery validation).

Emergency rotation

Revoke compromised material, invalidate sessions, preserve evidence, and test that recovery remains readable.

Revoke immediatelyDelete the Secret or disable the credential provider at once to block further use.
Invalidate sessions and auditInvalidate any session that may have been issued with the compromised credential; review audit logs for unauthorized access.
Preserve evidenceBefore deletion, export audit logs and any related certificates for forensics.
Test recovery readabilityAfter revocation, verify that backups signed with the old key are still readable if they are part of your retention policy.

Emergency rotation order

ROTATION ORDER

01   01 New issued → dual trust/distribution → consumer validation
02   02 Test login, API, DB, agents, modules, backups, webhooks
03   03 Old revoked only after recovery and retained data remain usable
NEXT GUIDEAudit, observability, and administration