Skip to content

Token-Signierung

Der CMI STS Server signiert seine ausgestellten Token mit seinem privaten Schlüssel. Ressourcenserver prüfen die Integrität des Tokens mit einem öffentlichen Schlüssel. Zusammen bilden sie ein asymmetrisches Private-/Public-Schlüsselpaar. Der CMI STS Server veröffentlicht den Public-Schlüssel zum Verifizieren der Tokens über den Endpunkt /.well-known/openid-configuration (Discovery-Dokument).

Wichtig: Der private Schlüssel darf niemals in fremde Hände geraten. Wenn das passiert, kann ein Angreifer Tokens ausstellen, die für einen Ressourcenserver völlig legitim aussehen. Besteht der Verdacht, dass der private Schlüssel nicht autorisierten Personen bekannt ist, muss das Schlüsselpaar ausgetauscht werden.

Das Schlüsselpaar wird global über alle Mandanten verwendet und ist nicht Mandantenspezifisch.

CMI STS 3.5

Der Key Management Mechanismus des Duende IdentityServer Frameworks wird verwendet. Schüsselmaterial wird dabei standardmässig automatisch verwaltet. Es wird eine Schlüsselrotation durchgeführt.

Standardmässig wird alle 90 Tage ein neuer Schlüssel zum "Hauptschlüssel" (Rotation). Der neue Hauptschlüssel wird 14 Tage vor dem Ablauf des alten Hauptschlüssels über den Discovery-Endpunkt bekannt gegeben (Propagation). Der alte Hauptschlüssel wird nach dem Ablauf noch weitere 14 Tage zur Validierung älterer Tokens verwendet (Retention).

{
    "KeyManagement": {
        "Enabled": true,
        "KeyPath": "./keys",
        "RotationInterval": "90.00:00:00",
        "PropagationTime": "14.00:00:00",
        "RetentionDuration": "14.00:00:00",
        "HealthCheckAcceptLegacyMode": false,
        "SigningAlgorithms": [
            {
                "Name": "RS256",
                "UseX509Certificate": false
            }
        ]
    }
}
  • Enabled (optional, Standardwert: true): Aktiviert die automatische Schlüsselverwaltung. Wird die Schlüsselverwaltung deaktiviert, muss das Schlüsselmaterial manuell verwaltet werden.
  • KeyPath (optional, Standardwert: ./keys): Verzeichnispfad, in dem automatisch erzeugte Schlüssel abgelegt werden.
  • RotationInterval (optional, Standardwert: 90.00:00:00): Rotationsintervall für den Hauptschlüssel. (D.HH:mm:nn)
  • PropagationTime (optional, Standardwert: 14.00:00:00): Dauer, die der neue Hauptschlüssel im Discovery-Dokument vor dem Ablauf des alten Hauptschlüssels bekannt gegeben wird. (D.HH:mm:nn)
  • RetentionDuration (optional, Standardwert: 14.00:00:00): Dauer, in der Tokens die mit dem alten Hauptschlüssel signiert wurden, noch akzeptiert werden. (D.HH:mm:nn)
  • HealthCheckAcceptLegacyMode (optional, Standardwert: false): Ein Health-Check befindet sich im Status Unhealthy, wenn die Schlüsselrotation dekativiert ist oder im Status Degraded, wenn die Schlüsselrotation aktiviert ist, aber ein manuell verwalteter Schlüssel weiterhin vorhanden ist. Wird diese Option auf true gestellt, wird der Health-Check im Status Healthy verbleiben, auch wenn manuell verwaltetes Schlüsselmaterial verwendet wird.
  • SigningAlgorithms (optional): Ein Liste von erlaubten Signierungs-Algorithmen. Der erste Eintrag wird Standardmässig verwendet. Client-Konfigurationen können einen bestimmten Algorithmus vorschreiben. Ein Listeneintrag hat folgende Eigenschaften:
  • Name (erforderlich): Name des Algorithmus. Gültige Werte sind: RS256, RS384, RS512, PS256, PS384,PS512, ES256, ES384, ES512. Weitere Informationen können unter RFC 7518, 3. Cryptographic Algorithms for Digital Signatures and MACs abgerufen werden.
  • UseX509Certificate (optional, Standardwert: false): Ein X509 Zertifikat wird erzeugt um den Schlüssel zu verwalten. Nicht alle Algorithmen unterstützen diese Option.

Wichtig: Der CMI Desktop Client im Release 21 erfordert, dass der verwendete Signierungs-Algorithmus mit UseX509Certificate auf true konfiguriert wird. Diese Einschränkung ist mit Release >=22 nicht mehr gegeben.

Wird SigningAlgorithms nicht konfiguriert, verwendet der CMI STS automatisch folgende kompatible Konfiguration: * Name: RS256 * UseX509Certificate: true

Hinweis: Das vom STS verwendete Schlüsselmaterial wird über den Endpunkt <Mandanten-ID>/identity/.well-known/openid-configuration/jwks angeboten. Das folgende Beispiel zeigt zwei öffentliche Schlüssel. Der erste Schlüssel stellt seine Daten auch als X509 Zertifikat bereit (x5c & x5t), während der zweite Schlüssel dies nicht tut. Weitere Informationen können unter RFC 7517, 4. JSON Web Key (JWK) Format abgerufen werden.

json { "keys": [ { "kty": "RSA", "use": "sig", "kid": "6DEB8EFD158B2AE7EC1856172925C8DA", "x5t": "Mlmu6D0Nal3UN9189eUODb4KwW0", "e": "AQAB", "n": "mmtZYA-...", "x5c": [ "MIIDFDCCAf..." ], "alg": "RS512" }, { "kty": "RSA", "use": "sig", "kid": "E12667F641EBA7597DB81C235E63A54D", "e": "AQAB", "n": "xu89q...", "alg": "RS512" } ] }

Deprecated: CMI STS 3.0-3.4

Das Schlüsselmaterial wird manuell verwaltet.

Wichtig: Die folgenden Einstellungen sind veraltet, werden jedoch noch ausgewertet. In zukünftigen Versionen kann diese Funktionalität entfernt werden. Siehe auch in den Migrationsanweisungen. Es handelt sich um eine statische Schlüsselkonfiguration. Schlüssel werden nicht automatisch ausgetauscht.

Hinweis: Wenn das Schlüsselpaar ausgetauscht wird, muss der CMI STS neu gestartet werden. Alle Ressourcenserver (z.b. der CMI Server) und Clients die Discovery-Daten aus /.well-known/openid-configuration im Cache halten, müssen ebenfalls neu gestartet werden oder ihren Cache löschen.

Die Schlüsselpaar-Eigenschaften werden wie gefolgt konfiguriert:

{
    "Signing": {
        "Type": "<Typ>",
        // Typ-spezifische Eigenschaften.
    }
}

Es werden zwei Typen von Schlüsselpaaren unterstützt, Pfx und Keypair. Wenn Type nicht konfiguriert ist, wird Pfx angenommen.

Keypair

{
    "Signing": {
        "Type": "Keypair",
        "PublicKeyFile": "./cert.pem",
        "PrivateKeyFile": "./cert.key"
    }
}
  • PublicKeyFile (optional, Standardwert: ./cert.pem): Dateipfad zum öffentlichen Schlüssel.
  • PrivateKeyFile (optional, Standardwert: ./cert.key): Dateipfad zum privaten Schlüssel.

Der CMI STS erzeugt kein Keypair selbstständig. Beide Dateien müssen durch ein externes Tool erzeugt werden. Ein solches Schlüsselpaar kann beispielsweise mit dem Programm openssl erzeugt werden.

Pfx

Wichtig: Ab Version 3.5 wird keine PFX-Datei mehr automatisch erzeugt. Bestehende PFX-Dateien werden jedoch noch gelesen. Stattdessen sollte das automatische Schlüsselmanagement verwendet werden.

{
    "Signing": {
        "Type": "Pfx",
        "PfxFile": "./cert.pfx",
        "PfxPassword": "12345",
        "PfxValidForDays": 365
    }
}
  • PfxFile (optional, Standardwert: ./cert.pfx): Dateipfad zu einer PFX-Datei, die den öffentlichen und privaten Schlüssel enthält.
  • PfxPassword (optional, Standardwert: 12345): Passwort, mit der die PFX-Datei geöffnet werden kann.
  • PfxValidForDays (optional, Standardwert: 365): Gültigkeitsdauer des in der PFX-Datei enthaltenen Zertifikats, wenn das Zertifikat generiert wird. Das Zertifikat hat zwar eine Gültigkeitsdauer, diese ist jedoch nicht relevant für die Funktionsweise. Es wird jeweils nur das Schlüsselpaar benötigt. Das Zertifikat darf ablaufen.