Key-Rotation für JWT - ohne Token zu invalidieren

Warum Schlüssel rotiert werden

Kryptographische Schlüssel haben eine Lifetime. Gründe für Rotation:

• Compliance-Vorgaben (PCI-DSS, ISO 27001): Keys müssen alle X Monate rotiert werden.
• Suspected Compromise: Vault wurde gehackt, ein Admin-Account wurde missbraucht, Mitarbeiter mit Key-Zugang hat das Unternehmen verlassen.
• Algorithm-Migration: Wechsel von RS256 auf ES256 oder EdDSA.
• Best Practice: Defense-in-Depth, regelmäßige Rotation reduziert Angriffsfläche.

Naiv: einfach Key tauschen

Anti-Pattern: Issuer-Service starten mit neuem Key, alle Verifier wissen es noch nicht → alle in-flight Tokens werden abgelehnt → Massen-Ausloggen aller User.

Bei einem System mit 50k aktiven Usern wäre das ein Incident - auch wenn die Maßnahme an sich richtig ist.

Pattern: zwei Keys parallel (Overlap)

Über einen Übergangszeitraum sind ZWEI Keys aktiv:

1. Tag 0: Nur Key A aktiv. Alle Tokens mit Key A signiert.
2. Tag 1: Key B wird zum Issuer hinzugefügt. NEUE Tokens werden mit B signiert. ALTE Tokens (mit A) werden noch akzeptiert.
3. Tag 1 bis Tag 1 + Refresh-Lifetime: Beide Keys parallel im JWKS. Alle aktiven Tokens werden in dem Zeitraum natürlich refresht (mit neuem Key signiert).
4. Tag 1 + Refresh-Lifetime + Buffer: Key A wird aus JWKS entfernt. Tokens, die mit A signiert sind, werden ab jetzt abgelehnt.

Beispiel mit 30-Tage-Refresh-Lifetime: 30 Tage Overlap + 3 Tage Buffer = 33 Tage Übergang. Während dieser Zeit kann jede laufende Session ohne Re-Login auf den neuen Key wechseln.

Was das kid-Header tut

Jedes Token hat im Header einen kid (Key ID): "ich wurde mit Key kid=abc123 signiert". Verifier schaut im JWKS nach kid=abc123 und holt den passenden Public Key.

// Header
{
  "alg": "RS256",
  "kid": "key-2026-04",
  "typ": "JWT"
}

// JWKS-Endpoint /.well-known/jwks.json
{
  "keys": [
    { "kid": "key-2026-04", "kty": "RSA", "n": "...", "e": "AQAB", "alg": "RS256" },
    { "kid": "key-2026-01", "kty": "RSA", "n": "...", "e": "AQAB", "alg": "RS256" }
  ]
}

Während der Overlap-Phase enthält das JWKS beide Keys. Verifier-Code:

function verify(token) {
  const header = decodeHeader(token);
  const jwks = fetchJWKS();  // cached
  const matchingKey = jwks.keys.find(k => k.kid === header.kid);
  if (!matchingKey) {
    refreshJWKS();  // vielleicht ist ein Key dazugekommen
    return verify(token);  // einmal retry
  }
  return verifyWithKey(token, matchingKey);
}

JWKS-Caching beachten

Wenn Verifier das JWKS aggressiv cachen (z.B. 24 h), sehen sie den neuen Key erst nach 24 h. Während dieser Zeit lehnen sie Tokens mit dem neuen kid ab.

Lösungen:

• Cache-Control-Headers auf JWKS-Endpoint setzen, z.B. max-age=3600 (1 h).
• Lazy-Refresh: bei kid-Lookup-Miss einmal frisch nachladen, statt blind aus Cache.
• Pre-Announcement: neuen Key 1-2 Tage vor Issuer-Aktivierung schon ins JWKS aufnehmen, damit Caches sich anpassen.

HMAC-Schlüssel rotieren

Bei HS256 ist das schwieriger, weil Issuer und Verifier denselben Secret teilen. Pattern: Issuer und Verifier müssen beide Secrets parallel kennen.

// Verifier-Pseudo-Code
const secretsCurrent = ["SECRET_2026_04", "SECRET_2026_01"];
for (const secret of secretsCurrent) {
  try {
    return jwt.verify(token, secret, { algorithms: ['HS256'] });
  } catch { /* try next */ }
}
throw new Error('Invalid');

Issuer signiert neue Tokens nur noch mit SECRET_2026_04. Nach Refresh-Lifetime + Buffer wird SECRET_2026_01 aus der Verifier-Config entfernt.

Notfall-Rotation

Bei suspected Compromise: keine 30 Tage Overlap. Sondern:

1. Neuen Key in JWKS aufnehmen, alten Key markieren als deprecated
2. Issuer auf neuen Key umstellen (sofort)
3. Alle aktiven Sessions aktiv invalidieren - z.B. Refresh-Token-Blacklist mit allen vor Zeitpunkt X ausgestellten Tokens
4. Alle User müssen sich neu einloggen - akzeptables Übel im Notfall

Automatisierte Rotation

Tools wie AWS KMS, Google Cloud KMS, HashiCorp Vault unterstützen automatische Key-Rotation. Vault z.B.: vault write transit/keys/my-jwt-key/rotate generiert neuen Key, JWKS-Endpoint wird automatisch updated. Verifier müssen ihre JWKS-Caches "refreshen" - was sie via Cache-Control sowieso periodisch tun.

Mehr zum JWKS-Format und Endpoint-Design im Ratgeber JWKS-Endpoint.