Skip to content

Migration von CMI STS 3.0-3.4 auf CMI STS 3.5

Dieses Kapitel fasst das Update von Version 3.0-3.4 auf 3.5 zusammen.

Die wichtigsten Änderungen in der Version 3.5 sind:

Schritt 1: Basis-Update (Non-Breaking-Changes)

Das Basis-Update folgt dem Standard-Update-Verfahren. Zusätzlich sind folgende Punkte zu beachten:

  1. Erfolgt das Hosting mittels IIS, musst das Hosting Bundle .NET Core 6.0.X vor dem Update installiert werden. Siehe auch Betrieb mit IIS unter Windows.
  2. Das bestehende Schlüsselmaterial (PFX-Datei cert.pfx oder Keypair-Dateien) kann vorerst beibehalten werden (Siehe auch Token-Signierung).
  3. Falls der CMI STS skaliert betrieben wird, muss die Konfiguration ergänzt werden. Die automatische Schlüsselverwaltung benötigt ein Verzeichnis, dass von allen CMI STS Instanzen gemeinsam verwendet werden kann (Siehe auch Token-Signierung und Skalierung).

    json "KeyManagement": { "KeyPath": "<shared directory path>" }

  4. Starten des CMI STS.
  5. Verifikation der automatischen Schlüsselverwaltung: Im Verzeichnis ./keys (bzw. falls konfigurativ überschrieben, im Verzeichnis von KeyManagement.KeyPath ), sollte der CMI Server mindestens eine JSON-Datei angelegt haben, nachdem die erste Anmeldung via dem CMI STS durchgeführt wurde. Die JSON-Datei enthält verschlüsseltes Schlüsselmaterial.

Nach dem Update wird sich der Monitoring-Endpunkt (/health) möglicherweise im Status Health Degraded befinden. Der Health-Endpunkt teilt mit, dass die Migration auf die automatische Schlüsselverwaltung nicht abgeschlossen ist.

Schritt 2: Migration auf die automatische Schlüsselverwaltung (Breaking-Changes)

Wenn das bestehende Schlüsselmaterial (PFX-Datei cert.pfx oder Keypair-Dateien) nicht entfernt wurde, wird dieses weiterhin verwendet. Alle Komponenten die über das Discovery-Dokument den Public-Key aus diesem Schlüsselmaterial verwenden, funktionieren weiterhin. Noch gültige ausgestellte Access-Token können weiterhin verwendet werden.

Um vollständig auf die automatische Schlüsselverwaltung zu wechseln, müssen die manuell verwalteten Schlüssel entfernt werden. Wenn der CMI STS Tokens mit neuem Schlüsselmaterial signiert und abhängige Clients und Komponenten ein veraltetes Discovery-Dokument verwenden, lehnen diese neue Tokens ab.

Daher müssen abhängige Komponenten ihr zwischengespeichertes Discovery-Dokument aktualisieren, wenn das manuell verwaltete Schlüsselmaterial vom CMI STS entfernt wird. Das kann auf folgende weise erfolgen:

  • Viele Komponenten rufen das Discovery-Dokument regelmässig bei CMI STS ab. Die neuen Public-Keys werden von den meisten Komponenten nach einigen Stunden bis einem Tag übernommen.
  • Um den Vorgang zu beschleunigen, können die betroffenen Komponenten und Clients neu gestartet werden. Das entfernt das Discovery-Dokument aus den Caches.

Hinweis: Manuell verwaltetes Schlüsselmaterial hat Vorrang vor allen Schlüsseln, die von der automatischen Schlüsselverwaltung erstellt wurden. Die manuelle und die automatische Schlüsselverwaltung können zur selben Zeit aktiv sein. Der im Discovery-Dokument referenzierte Endpunkt .well-known/openid-configuration/jwks gibt alle öffentlichen Schlüssel bekannt.

Es wird daher empfohlen, dass dieser Schritt der Migration frühestens 24 Stunden nach dem Basis-Update durchgeführt wird. Das reduzierten den möglichen Impact des Changes. Es gibt den abhängigen Komponenten und Clients Zeit, über den Discovery-Endpunkt sowohl den alten als auch den neuen öffentlichen Schlüssel kennenzulernen.

Hinweis: Der CMI Server aktualisiert die Discovery-Daten ungefähr alle 24 Stunden automatisch. Viele CMI Komponenten, die den Clients Credentials Flow verwenden, aktualisieren die Discovery-Daten, sobald ein neues Access-Token benötigt wird. Hier kann über die konfigurierte Access-Token-Lifetime bestimmt werden, wie oft das Discovery-Dokument aktualisiert wird.

Grundsätzlich sind die folgende Schritte erforderlich um die Migration durchzuführen (siehe auch Token-Signierung):

  1. Sicherstellen, dass das Basis-Update erfolgreich durchgeführt wurde
  2. CMI STS stoppen
  3. Falls vorhanden, in der Konfiguration folgende Sektion vollständig löschen:

    jsonc "Signing": { // ... }

  4. Das alte Schlüsselmaterial löschen. Standardmässig ist dies die Datei ./cert.pfx.
  5. CMI STS starten
  6. Abhängige Komponenten bei Bedarf neu starten, damit diese ihr zwischengespeichertes Discovery-Dokument aktualisieren. U.a. den CMI Server, Push- und WebDav-Service.