Key Rotation

OIDC issuers rotate their signing keys periodically. Understanding how key rotation works is important to ensure uninterrupted token verification when using oidc.pub.

The key overlap strategy

Most OIDC providers — including Kubernetes, HashiCorp Vault, and GitLab — follow a key overlap strategy when rotating signing keys. Rather than replacing the old key immediately, the new key is added alongside it. Both keys coexist in the JWKS for a grace period so that tokens signed with the old key can still be verified.

How it works

  1. The issuer generates a new signing key and adds it to the JWKS
  2. New tokens are signed with the new key
  3. Old keys remain in the JWKS for a grace period — typically the token's maximum lifetime (e.g. 24 hours for Kubernetes service account tokens, or the configurable verification_ttl in HashiCorp Vault)
  4. After the grace period, old keys are removed from the JWKS

What this means for oidc.pub

Because old and new keys overlap, your sync does not need to happen at the exact moment of rotation. As long as the updated JWKS (containing both old and new keys) is uploaded to oidc.pub before the old key is removed, relying parties will be able to verify both old and new tokens without interruption.

A sync interval of 5–60 minutes is typically sufficient. The default interval of the sync worker is 300 seconds (5 minutes), which is well within the overlap window of all common OIDC issuers.

Provider-specific details

Kubernetes

Kubernetes keeps old keys in the JWKS for the duration of the longest-lived bound service account token. The default maximum token lifetime is 24 hours (--service-account-max-token-expiration), giving you a large window to sync the updated JWKS.

HashiCorp Vault

Vault keeps old keys for the duration of the named key's verification_ttl (default 24 hours). You can inspect the current keys and their expiry via vault read identity/oidc/.well-known/keys.

GitLab

GitLab rotates CI job token signing keys internally. The old key remains available in the JWKS for the duration of any running pipeline that may have received a token signed with it. A sync interval of 15–60 minutes covers this comfortably.

Recommended setup

The simplest way to handle key rotation is to deploy the sync worker with its default 5-minute interval. It will pick up new keys as they appear in the JWKS and push the full key set (old + new) to oidc.pub automatically.

If you sync manually, ensure your cron job or CI schedule runs frequently enough that the new JWKS is uploaded before any relying party encounters a token signed with a key it hasn't seen yet.