Skip to Content

Signaturschlüssel

Die Schlüssel, die OIDC- und SAML-Token signieren, einsehen, rotieren und widerrufen, und warum die Rotation für angebundene Anwendungen wichtig ist.

Die Plattform signiert die von ihr ausgestellten Token, also OIDC ID-Token und Access-Token sowie OAuth-/OIDC-Assertions, mit einem privaten Signaturschlüssel. Angebundene Anwendungen prüfen diese Signaturen gegen den passenden öffentlichen Schlüssel, den die Plattform an ihrem JWKS-Endpunkt (/.well-known/jwks) veröffentlicht. Auf der Registerkarte Signing keys können Sie diese Schlüssel einsehen, rotieren und widerrufen.

Der Reiter „Signaturschlüssel" in den Systemeinstellungen

Schlüssel-Lebenszyklus

Verfolgen Sie ein Token: Bei der Ausstellung wird es mit dem aktuellen Schlüssel signiert und trägt dessen Kennung (kid) im Header. Die Anwendung liest die kid, sucht den Schlüssel im veröffentlichten Key Set und prüft die Signatur. Das Key Set enthält höchstens drei Schlüssel: den, der als Nächstes signieren wird, den, der jetzt signiert, und den, der bis zur letzten Rotation signiert hat. Solange ein Schlüssel im Set steht, sind Token mit seiner kid prüfbar; ein widerrufener Schlüssel verlässt das Set, und seine Token scheitern ab dann.

Der Tab Signing keys zeigt diese drei Schlüssel mit ihrem Status:

StatusRolle
NextWird vorab veröffentlicht, damit Anwendungen ihn bereits kennen, wenn er zu signieren beginnt.
CurrentSigniert jedes jetzt ausgestellte Token.
PreviousHat bis zur letzten Rotation signiert. Steht weiterhin im Key Set, sodass Token mit seiner kid prüfbar bleiben, bis Sie ihn widerrufen.

Jeder Schlüssel wird durch eine Key ID (kid) identifiziert; Anwendungen wählen darüber beim Prüfen eines Tokens den richtigen öffentlichen Schlüssel. Ein Badge neben der Key ID zeigt die Schlüssellänge in Bit. Neu erzeugte Schlüssel sind RSA mit 3072 Bit; ältere 2048-Bit-Schlüssel bleiben für die Prüfung gültig und werden mit jeder Rotation durch die stärkere Länge ersetzt.

Schlüssel einsehen und exportieren

Für jeden Schlüssel in der Liste können Sie über das Aktionsmenü:

  • das Signaturzertifikat mit Copy in die Zwischenablage kopieren,
  • die Zertifikatsdetails mit View anzeigen,
  • das Zertifikat mit Download als .pem-Datei herunterladen.

Das ist nützlich, wenn eine Anwendung das Zertifikat manuell konfiguriert benötigt, statt es vom JWKS-Endpunkt abzurufen.

Warum Rotation wichtig ist

Regelmäßige Schlüsselrotation begrenzt den Schaden, falls ein Schlüssel jemals kompromittiert wird, und ist eine verbreitete Compliance-Anforderung. Wie viel Arbeit eine Rotation verursacht, hängt davon ab, wie jede Anwendung den Schlüssel erhalten hat:

  • Ein SAML- oder WS-Federation-Service-Provider, der einem fest hinterlegten Zertifikat vertraut, muss das Zertifikat des Next-Schlüssels erhalten, bevor Sie rotieren; andernfalls schlägt seine Signaturprüfung nach der Umstellung fehl.
  • Eine OIDC-Anwendung mit manuell konfiguriertem Schlüssel braucht dieselbe Vorbereitung.
  • Eine Anwendung, die das Key Set vom JWKS-Endpunkt abruft, übernimmt den neuen Schlüssel von selbst, weil der Endpunkt den nächsten, den aktuellen und den vorherigen öffentlichen Schlüssel veröffentlicht. Für diese Anwendungen erfolgt die Rotation ohne Ausfallzeit.

Hinweis: Die Rotation betrifft OIDC- und OAuth-Anwendungen. Nach einer Rotation kann es bis zu etwa 30 Sekunden dauern, bis die Änderung vollständig wirksam ist.

Rotieren und Widerrufen

Die Aktionen finden Sie unter Kritische Aktionen am Seitenende. Jede verlangt eine Bestätigung.

AktionWas passiertAuswirkung auf bestehende Token
Rotate keyDer Next-Schlüssel wird Current; der bisherige Current-Schlüssel wird Previous. Gab es bereits einen Previous-Schlüssel, wird er widerrufen und wandert in die Widerrufsliste.Bereits ausgestellte Token bleiben prüfbar; der Previous-Schlüssel bleibt im Key Set.
Rotate & revoke keyRotiert wie oben und widerruft den Previous-Schlüssel sofort.Token mit der kid des Previous-Schlüssels sind nicht mehr prüfbar.
Revoke keyWiderruft den Previous-Schlüssel ohne Rotation.Token mit der kid dieses Schlüssels sind nicht mehr prüfbar.

Die drei jüngsten Widerrufe bleiben mit ihrem Datum aufgelistet, für Audit-Zwecke.

Empfohlene Reihenfolge

  1. Stellen Sie sicher, dass jede Anwendung mit manuell hinterlegtem Zertifikat dem Next-Schlüssel vertraut.
  2. Verwenden Sie Rotate key. Neue Token werden nun mit dem neuen Schlüssel signiert; ältere Token bleiben gültig.
  3. Sobald Sie sicher sind, dass keine Anwendung mehr auf den Previous-Schlüssel angewiesen ist, widerrufen Sie ihn.

Verwenden Sie Rotate & revoke key nur, wenn zuvor ausgestellte Token sofort ungültig werden müssen, zum Beispiel nach einer vermuteten Schlüsselkompromittierung.

Achtung: Das Widerrufen eines Schlüssels, auf den sich Anwendungen noch verlassen, bricht deren Tokenprüfung. Rotieren Sie zuerst, bestätigen Sie, dass die Anwendungen umgestellt haben, und widerrufen Sie erst danach.

Zentrale Schlüssel vs. anwendungsspezifisches Signaturzertifikat

Signaturschlüssel tauchen an zwei Stellen auf, und sie sind nicht dasselbe:

  • Die zentralen Signaturschlüssel auf dieser Seite signieren jedes OIDC ID-Token und Access-Token, das die Plattform ausstellt, sowie standardmäßig die von ihr erzeugten SAML-/WS-Federation-Assertions. Eine Rotation hier betrifft alle Anwendungen, die den veröffentlichten Schlüsseln der Plattform vertrauen.
  • Ein anwendungsspezifisches Signaturzertifikat kann stattdessen auf einer einzelnen SAML- oder WS-Federation-Anwendung konfiguriert werden, wenn dieser Service Provider einem bestimmten Zertifikat statt dem zentralen Schlüssel der Plattform vertrauen soll.

Meldet ein Service Provider einen Signaturfehler, prüfen Sie zuerst, welchem Schlüssel er vertraut: dem zentralen, am JWKS-Endpunkt veröffentlichten Schlüssel oder einem auf genau dieser Anwendung hinterlegten Zertifikat. Wo die Zugangsdaten einer Anwendung gesetzt werden, zeigt Integrationen → Anwendungen.

Auf dieser Seite