Zum Hauptinhalt springen

Signaturschlüssel rotieren (OSS)

hinweis:

Wenn du Logto Cloud verwendest, kannst du Signaturschlüssel in der Console UI rotieren. Siehe bitte dieses Tutorial.

Logto OSS unterstützt das Rotieren von Signaturschlüsseln seit v1.8.

Logto OIDC-Signaturschlüssel, auch bekannt als „OIDC-Private Keys“ und „OIDC-Cookie-Keys“, sind die Signaturschlüssel, die verwendet werden, um JWTs (Zugangstokens (Access tokens) und ID-Tokens (ID tokens)) sowie Browser-Cookies in Logto-Anmeldesitzungen zu signieren.

Das regelmäßige Rotieren deiner Signaturschlüssel kann das Risiko eines möglichen Schlüsselkompromisses verringern. Logto empfiehlt, deine Signaturschlüssel mindestens einmal pro Jahr zu rotieren.

OIDC Private Signaturschlüssel rotieren​

Verwende den folgenden CLI-Befehl, um einen neuen OIDC Private Signaturschlüssel zu generieren. Standardmäßig wird der neue Schlüssel sofort wirksam. Um die Rotation zu planen und Clients Zeit zu geben, JWKS zu aktualisieren, bevor der neue Schlüssel JWTs signiert, konfiguriere eine Schonfrist.

Verfügbare Optionen:

--type          (Optional) Der Signaturschlüssel-Algorithmus für deine JWTs.
                Werte sind "rsa" oder "ec". Standard ist "ec".
--gracePeriod   (Optional) Schonfrist in Sekunden für geplante Private-Key-Rotation.
                Standard ist die Umgebungsvariable PRIVATE_KEY_ROTATION_GRACE_PERIOD oder 0, falls nicht gesetzt.
logto db config rotate oidc.privateKeys --type rsa

Beispiel: Um den neuen Private Key für 4 Stunden zu planen, bevor er aktiv wird:

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

Du kannst auch die Standard-Schonfrist für die Private-Key-Rotation mit einer Umgebungsvariable festlegen:

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

Setze diese Umgebungsvariable beim Logto-Dienst, wenn du über die Admin Console oder Management API rotierst, oder in der Shell, in der du den CLI-Befehl ausführst, wenn du über CLI rotierst.

Verwende den folgenden CLI-Befehl, um einen neuen OIDC Cookie Key zu generieren. Die Rotation von Cookie Keys unterstützt keine Schonfrist.

logto db config rotate oidc.cookieKeys

Was passiert mit den vorherigen Schlüsseln?​

Für OIDC Private Keys behält Logto bis zu drei Schlüssel während der geplanten Rotation:

  • Next: Der neue Schlüssel, der auf das Ende der Schonfrist wartet.
  • Current: Der Schlüssel, der aktuell zum Signieren neu ausgestellter JWTs verwendet wird.
  • Previous: Der zuletzt herausrotierte Schlüssel, der aufbewahrt wird, damit bestehende JWTs weiterhin gültig bleiben.

Nach Ablauf der Schonfrist wird der Next-Schlüssel zu Current, der alte Current-Schlüssel zu Previous und der älteste Previous-Schlüssel wird entfernt.

Für Cookie Keys behält Logto den aktuellen und den vorherigen Schlüssel. Sei vorsichtig beim Löschen vorheriger Schlüssel, da dies unerwartete Probleme verursachen kann. Es wird empfohlen, den vorherigen Schlüssel so lange zu behalten, bis du sicher bist, dass alle bestehenden Sitzungen oder Tokens, die damit signiert wurden, abgelaufen sind.

Fehlerbehebung​

Logto als OIDC Provider in Cloudflare Zero Trust verwenden​

Wenn du Logto als OIDC Provider mit Cloudflare Zero Trust verwenden möchtest, beachte bitte, dass Cloudflare keine OIDC Provider mit ECDSA-Algorithmen unterstützt. Stelle beim Rotieren von OIDC Private Signaturschlüsseln sicher, dass du den RSA-Algorithmus verwendest, indem du --type rsa im Rotationsbefehl angibst:

logto db config rotate oidc.privateKeys --type rsa