Signaturschlüssel

Logto OIDC-Signaturschlüssel, auch bekannt als „OIDC-Private Keys“ und „OIDC-Cookie-Keys“, sind die Signaturschlüssel, die zum Signieren von JWTs (Zugangstokens (Access tokens) und ID-Tokens (ID tokens)) sowie Browser-Cookies in Logto Anmeldesitzungen verwendet werden. Diese Signaturschlüssel werden beim Initialisieren der Logto-Datenbank (Open-Source) oder beim Erstellen eines neuen Mandanten (Cloud) generiert und können über CLI (Open-Source), Management APIs oder die Console UI verwaltet werden.

Standardmäßig verwendet Logto den Elliptische-Kurven-Algorithmus (EC), um digitale Signaturen zu erzeugen. Da Benutzer jedoch häufig JWT-Signaturen überprüfen müssen und viele ältere Tools den EC-Algorithmus nicht unterstützen (sondern nur RSA), haben wir die Möglichkeit implementiert, private Schlüssel zu rotieren und den Signaturalgorithmus auszuwählen (einschließlich RSA und EC). Dies gewährleistet die Kompatibilität mit Diensten, die veraltete Signaturprüfungs-Tools verwenden.

hinweis:

Theoretisch sollten Signaturschlüssel nicht kompromittiert werden und haben keine Ablaufzeit, sodass eine Rotation nicht zwingend erforderlich ist. Dennoch kann das regelmäßige Rotieren des Signaturschlüssels nach einer bestimmten Zeitspanne die Sicherheit erhöhen.

Wie funktioniert das?

• OIDC-Private Key Beim Initialisieren einer Logto-Instanz wird automatisch ein Schlüsselpaar aus öffentlichem und privatem Schlüssel generiert und im zugrundeliegenden OIDC-Provider registriert. Wenn Logto ein neues JWT (Zugangstoken oder ID-Token) ausstellt, wird das Token mit dem privaten Schlüssel signiert. Gleichzeitig kann jede Client-Anwendung, die ein JWT erhält, den zugehörigen öffentlichen Schlüssel verwenden, um die Signatur des Tokens zu überprüfen und sicherzustellen, dass das Token nicht von Dritten manipuliert wurde. Der private Schlüssel ist auf dem Logto-Server geschützt. Der öffentliche Schlüssel hingegen ist, wie der Name schon sagt, für jeden zugänglich und kann über die /oidc/jwks-Schnittstelle des OIDC-Endpunkts abgerufen werden. Beim Generieren des privaten Schlüssels kann ein Signaturalgorithmus angegeben werden; Logto verwendet standardmäßig den EC-Algorithmus (Elliptische Kurve). Administratoren können den Standardalgorithmus durch Rotation der privaten Schlüssel auf RSA (Rivest-Shamir-Adleman) umstellen.
• OIDC-Cookie-Key Wenn ein Benutzer einen Anmelde- oder Registrierungsprozess startet, wird auf dem Server eine „OIDC-Sitzung“ erstellt sowie eine Reihe von Browser-Cookies. Mit diesen Cookies kann der Browser die Logto Experience API nutzen, um im Namen des Benutzers verschiedene Interaktionen durchzuführen, wie Anmeldung, Registrierung und Passwortzurücksetzung. Im Gegensatz zu JWTs werden die Cookies jedoch nur von Logto OIDC selbst signiert und überprüft; asymmetrische Kryptografie ist hierfür nicht erforderlich. Daher gibt es keine zugehörigen öffentlichen Schlüssel für Cookie-Signaturschlüssel und auch keine asymmetrischen Verschlüsselungsalgorithmen.

Signaturschlüssel über die Console UI rotieren

Logto bietet die Funktion „Signaturschlüssel-Rotation“, mit der du einen neuen OIDC-Private Key und Cookie Key in deinem Mandanten erstellen kannst.

1. Navigiere zu Console > Mandanteneinstellungen > OIDC-Konfigurationen. Dort kannst du sowohl OIDC-Private Keys als auch OIDC-Cookie-Keys verwalten.

2. Um den Signaturschlüssel zu rotieren, klicke auf die Schaltfläche „Private Keys rotieren“ oder „Cookie Keys rotieren“. Beim Rotieren der Private Keys kannst du den Signaturalgorithmus ändern.

3. Du findest dort eine Tabelle, die alle verwendeten Signaturschlüssel auflistet. Für OIDC-Private Keys kannst du den vorherigen Schlüssel löschen, aber nicht den aktuellen oder nächsten Schlüssel. Für OIDC-Cookie-Keys kannst du den vorherigen Schlüssel löschen, aber nicht den aktuellen Schlüssel.

   Status	Beschreibung
   Next	Dieser Status wird für die gestaffelte Rotation von OIDC-Private Keys verwendet. Der Schlüssel wurde erstellt, aber Logto verwendet ihn erst nach Ablauf der Schonfrist zum Signieren neuer JWTs.
   Current	Dieser Schlüssel wird aktuell von Logto zum Signieren neu ausgestellter JWTs oder Cookies verwendet.
   Previous	Bezieht sich auf einen Schlüssel, der zuvor verwendet wurde, aber inzwischen rotiert wurde. Bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, bleiben gültig, bis sie ablaufen oder der Schlüssel gelöscht wird.

Bitte beachte, dass die Rotation die folgenden drei Aktionen umfasst:

1. Erstellen eines neuen Signaturschlüssels: Für OIDC-Private Keys kann Logto den neuen Schlüssel zunächst als „Next“ bereitstellen, sodass deine Anwendungen und APIs Zeit haben, den öffentlichen Schlüssel vom /oidc/jwks-Endpunkt zu aktualisieren, bevor der neue Schlüssel zum Signieren verwendet wird.
2. Rotation des aktuellen Schlüssels: Wenn die Rotation wirksam wird, wird der „Next“-Schlüssel zum „Current“ und der bisherige „Current“-Schlüssel zum „Previous“. Mit dem vorherigen Schlüssel signierte Tokens bleiben weiterhin gültig.
3. Entfernen des ältesten vorherigen Schlüssels: Logto behält maximal einen „Previous“-Private Key. Existiert bereits ein vorheriger Private Key, wenn der gestaffelte Schlüssel aktuell wird, wird der ältere vorherige Schlüssel entfernt.

Für Logto Cloud tritt die Rotation des OIDC-Private Keys nach einer Schonfrist von 4 Stunden in Kraft. Während dieser Zeit wird der neue Schlüssel vorbereitet und über JWKS bereitgestellt, bevor Logto beginnt, neu ausgestellte JWTs damit zu signieren. In der Console-Tabelle zeigt die Spalte Wirksam ab an, wann ein gestaffelter „Next“-Schlüssel zum „Current“ wird.

Für selbst gehostete OSS-Deployments beträgt die Standard-Schonfrist für die Rotation privater Schlüssel 0 Sekunden, was bedeutet, dass die Rotation sofort erfolgt. Um eine gestaffelte Rotation zu nutzen, setze die Umgebungsvariable PRIVATE_KEY_ROTATION_GRACE_PERIOD im Logto-Service oder übergebe einen expliziten Wert für rotationGracePeriod im Request-Body beim Aufruf des Management API-Endpunkts POST /api/configs/oidc/private-keys/rotate.

warnung:

Vermeide es, Signaturschlüssel wiederholt zu rotieren, bevor die ausstehende Rotation wirksam wird, es sei denn, du möchtest den gestaffelten „Next“-Schlüssel absichtlich ersetzen.

Das zu frühe Löschen des einzigen „Previous“-Schlüssels kann dazu führen, dass bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, ungültig werden.

Verwandte Ressourcen

Einführung in EC- und RSA-Signaturalgorithmen in JWT