Skip to content

Migration vom CMI STS 2 auf 3

Dieses Kapitel unterstützt bei der Migration einer CMI STS 2 Installation zu einer CMI STS 3 Installation. Mit dem CMI STS 2 war es üblich, für jeden Mandanten eine eigene Installation vorzunehmen. Da wir Verbesserungen bezüglich der Multi-Mandantenfähigkeit beim CMI STS 3 integriert haben, sollen nun alle Mandanten mit einer einzigen CMI STS 3 Installation bedient werden.

Vorbereitung

  1. Identifizieren notieren aller Clients und Schnittstellen, die der Kunde im Einsatz hat. Der CMI interne Wiki-Artikel Schnittstellen und Integrationen CMI Lösungsplattform listet alle Module auf. Die Spalte "STS 3" gibt Auskunft darüber, ob das Modul den CMI STS 3 bereits unterstützt. Ist dies nicht der Fall, muss die Migration zu einem späteren Zeitpunkt durchgeführt werden oder das Modul wird zuvor kompatibel gemacht.
  2. Alle Clients und Schnittstellen die den "Impersonation Grant" vom CMI STS 2 verwenden, benötigen nach der STS Umstellung potenziell eine Konfigurationsanpassung. Diese Schnittstellen sollten vorgängig notiert werden. Wenn kein direkter Zugriff auf diese Schnittstellen besteht, muss mit dem IT-Betreiber ein Zugriffstermin geplant werden.
  3. Gruppen- und Feldmapping-Einstellungen aus der bestehenden IdentityServer.json-Datei entnehmen und pro Mandant in einer Excel-Tabelle wie gefolgt zusammenstellen:
    • Gruppenmapping: Idp, ClaimType, ClaimValue, CMI Gruppe
    • Feldmapping: Idp, ClaimType, CMI Benutzer Feld
  4. Wenn kein direkter Zugriff auf den Server besteht, auf dem der CMI STS läuft, muss mit dem IT Betreiber geklärt werden, wie die Systemvoraussetzung für den CMI STS 3 installiert werden können (siehe Betrieb mit IIS unter Windows).
  5. Wenn der zweite Faktor eingesetzt wird, sollte eine Massenänderungslizenz vorhanden sein.

Es wird angenommen, dass bei den meisten Kunden folgendes Setup vorhanden ist:

  • IIS Web Site: sts.gemeinde.ch
    • Application: /tenantA (eigene STS 2 Installation, https://sts.gemeinde.ch/tenantA)
    • Application: /tenantB (eigene STS 2 Installation, https://sts.gemeinde.ch/tenantB)

Ist dies der Fall, können die bestehenden STS-URLs beibehalten werden, was den Change-Aufwand reduziert. Der CMI STS 3 wird direkt in die bestehende Web Site installiert und die bestehenden Applications entfernt. Hat der Kunde ein anderes Setup muss geklärt werden, in wie weit URLs beibehalten werden können. Möglicherweise muss der IT Betreiber neue TLS-Zertifikate bereitstellen.

Interne Notiz: Nicht bei jedem Kunden ist eine Massenänderungslizenz vorhanden. Die erforderlichen Schritte können auch mit einem Report gelöst werden. Diese wurden bisher noch nicht erstellt. Wenn ein solcher Report erstellt wird, bitten wir darum, diesen Report dem DevOps-Team zu kommen zu lassen. Wir aktualisieren dann diese Dokumentation.

Konfiguration migrieren

Dieses Kapitel geht davon aus, dass der CMI STS OnPremises installiert wird und die Konfiguration mittels JSON-Dateien erfolgt (siehe Konfiguration).

Die Datei appsettings.json wird mit einer minimalen nicht mandanten-spezifischen Konfiguration zusammen mit den Binaries geliefert. Die Datei appsettings.json dient als Ausgangslage für die neue Konfiguration.

Nicht mandanten-spezifische Einstellungen

Die folgende Tabelle zeigt eine Aufstellung von CMI STS 2 Einstellungen, die meistens nicht explizit migriert werden müssen. Entweder bestehen bereits sinnvolle Standardwerte für den CMI STS 3 oder die gelieferte appsettings.json konfiguriert diese mit Werten, die in den meisten Fällen zutreffend sind.

CMI STS 2 CMI STS 3
CookieValidity (global) CookieLifetime (mandanten-spezifisch)
FrameSupportEnabled CSP
HttpsEnabled Nicht erforderlich/kein Equivalent
PasswordResetSessionValidity Passwort-Link Nonce
DosProtection Nicht umgesetzt/kein Equivalent
CertificateForSigningFileName Signing
CertificateForSigningPassword Signing
LoggingLevel Logging
StsDetailLoggingEnabled Logging
LoggingPath Logging
Kein Equivalent Scopes

Das Standard-appsettings.json benötigt Anpassungen an den folgen Stellen:

  • Serilog.WriteTo[Name=File].path: Festlegen des Logverzeichnisses. Siehe Logging.
  • TenantConfigurationDirectory: Pfad, in dem Mandanten-Konfigurationen abgelegt werden. Dieser Eintrag kann entfernt werden, wenn Mandanten-Einstellungen nicht auf einzelne Dateien aufgeteilt werden. Siehe Mandanten.

Mandanten-spezifische Einstellungen

Wenn mehr als 2-3 Mandanten konfiguriert werden, wird empfohlen die Konfiguration auf mehrere Dateien aufzuteilen (siehe Mandanten).

Migration der ApiServer

Migration der ApiServer (beim CMI STS 3 teilweise auch als Downstream-Service bezeichnet):

CMI STS 2

{
     "ApiServers": [
         {
             "ApiServerUri": "https://proxy.gemeinde.ch/mandant1/webapiprivate",
             "ApiServerId": "mandant1",
             "Description": "Mandant 1"
         },
         {
             "ApiServerUri": "https://proxy.gemeinde.ch/mandant2/webapiprivate",
             "ApiServerId": "mandant2",
             "Description": "Mandant 2"
         }
     ]
 }

CMI STS 3

{
     "Tenants": {
         "mandant1": {
             "CmiPrivateUri": "https://proxy.gemeinde.ch/mandant1/webapiprivate"
         },
         "mandant2": {
             "CmiPrivateUri": "https://proxy.gemeinde.ch/mandant2/webapiprivate"
         }
     }
 }

Migration der Identity Provider

Identity Provider werden nicht mehr global konfiguriert, sondern bei ihren jeweiligen Mandanten. Die Eigenschaften eines IDPs können nicht immer 1:1 übernommen werden. Das Kapitel Identity Provider (IDP) beschreibt die verfügbaren Optionen und sollte für diesen Schritt als Referenz herangezogen werden.

CMI STS 2

{
    "OpenIdConnectIdps": [
        {
            "Enabled": "true",
            "AuthenticationType": "openid",
            "Caption": "auth0.com",
            "MetadataAddress": "https://[...]/.well-known/openid-configuration",
            "ClientId": "...",
            "ClientSecret": "...",
            "CallbackPath": "/identity/openid",
            "RedirectUri": "https://sts.gemeinde.ch/mandant1/identity/openid",
            "MappingClaim": "name",
            "GroupClaim": "role"
        }
    ],
    "WsFederationIdps": [
        {
            "Enabled": "true",
            "AuthenticationType": "o365",
            "Caption": "Office 365",
            "MetadataAddress": "https://[...]/2007-06/federationmetadata.xml",
            "Wtrealm": "https://gemeinde.ch/00000000-0000-0000-0000-000000000000",
            "CallbackPath": "/mandant1/identity/o365",
            "MappingClaim": "name"
        }
    ]
}

CMI STS 3

{
    "Tenants": {
        "mandant1": {
            "ExternalIdps": {
                "o365": {
                    "Type": "WsFed",
                    "IdClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
                    "MetadataAddress": "https://[...]/2007-06/federationmetadata.xml",
                    "Wtrealm": "https://gemeinde.ch/00000000-0000-0000-0000-000000000000"
                },
                "auth0": {
                    "Type": "OIDC",
                    "ClientId": "...",
                    "ClientSecret": "...",
                    "Authority": "https://gemeinde.eu.auth0.com",
                    "CallbackPath": "/signin-oidc-auth0",
                    "SignedOutCallbackPath": "/signout-callback-oidc-auth0",
                    "Scope": ["openid", "profile", "email", "phone", "address"],
                    "IdClaimType": "name"
                }
            }    
        }
    }
}

CMI hat sowohl beim CMI STS 2 als auch CMI STS 3 hersteller-spezifische Provider-Eigenschaften hinzugefügt, die wie gefolgt migriert werden:

CMI STS 2 CMI STS 3
MappingClaim * IdClaimType
GroupClaim Nicht erforderlich/Wird im CMI konfiguriert
** LogoutOptions UseProviderSignOut

* Der vollständige Claim-Type muss konfiguriert werden. Während der CMI STS 2 den Bezeichner name für den Claim-Type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name akzeptiert, muss beim CMI STS 3 der vollständige Claim-Type angegeben werden, wenn dieser so vom IDP geliefert wird (exakter Vergleich). Der Debug-Log-Level beider CMI STS Versionen schreibt die empfangenen Claims auf das Log. So lässt sich erkennen, wie der vom IDP ausgestellte Claim-Type lautet.

** Die Option LogoutOptions befindet sich in einer seperaten Sektion im JSON.

Migration der Clients

Clients werden nicht mehr global konfiguriert, sondern bei ihren jeweiligen Mandanten. Die Eigenschaften eines Clients können nicht immer 1:1 übernommen werden.

Das Kapitel Clients beschreibt für die meisten Clients gute Standardeinstellungen. Es wird empfohlen, die benötigten Clients aus diesem Kapitel in die neue Konfiguration zu kopieren. Anschliessend können die Eigenschaften RedirectUris und PostLogoutRedirectUris aus der CMI STS 2 Konfiguration übernommen werden.

CORS: Der CMI STS 2 unterstützt nur eine Allow-All-Origins-Policy, während beim CMI STS 3 eine Liste der erlaubten Origins mit AllowedCorsOrigins konfiguriert werden kann.

CMI STS 2 CMI STS 3
RedirectUris RedirectUris
PostLogoutRedirectUris PostLogoutRedirectUris
Kein Equivalent AllowedCorsOrigins

Client "metatool": Der CMI STS 2 besitzt einen impliziten Client mit den Namen metatool, der nicht konfiguriert werden muss. Dieser Client wird vom Desktop Client verwendet. Für den CMI STS 3 muss dieser Client explizit konfiguriert werden. Die Einstellungen im Kapitel Clients sind im Normalfall ausreichend.

Client "server": Der spezielle Client server existiert mit dem CMI STS 3 nicht mehr und kann daher nicht migriert werden. Dieser spezielle Client wird beim CMI STS 2 verwendet, um einen Impersonation Grant durchzuführen. Dieser Grant wurde aufgrund von Sicherheitsüberlegungen nicht mehr implementiert. Clients müssen stattdessen einen Client Credentials Grant oder einen Delegation Grant verwenden. Jeder Client, der ursprünglich den Impersonation Grant verwendet hat, erhält beim CMI STS 3 einen eigenen Client, der für den Client Credentials Grant oder Delegation Grant konfiguriert wird. Das Kapitel Clients dokumentiert einige der häufig eingesetzten Clients wie den Push Service oder WebDav Service. Die Dokumentation des Clients/der Komponente sollte ebenfalls Aufschluss geben, wie diese für den CMI STS 3 konfiguriert werden kann.

Migration der NetworkConfigurations (Selektoren)

Die automatischen Weiterleitungen werden nicht mehr global konfiguriert, sondern bei ihren jeweiligen Mandanten. Die NetworkConfigurations vom CMI STS 2 kann mit sogenannten Selektoren im CMI STS 3 abgebildet werden.

CMI STS 2

{
    "NetworkConfigurations":  [
        {
            "IpRange":  "185.157.0.236",
            "IdpUsed":  "o365"
        },
        {
            "IpRange":  "10.10.10.0/24",
            "IdpUsed":  "o365"
        },
        {
            "IpRange":  "10.10.20.0/24",
            "IdpUsed":  "o365"
        },
        {
            "IpRange":  "10.10.30.0/24",
            "IdpUsed":  "o365"
        }
    ]
}

CMI STS 3

{
    "Tenants": {
        "mandant1": {
            "ExternalIdpSelectors": [
                {
                    "NetworkRanges": [
                        "185.157.0.236/32",
                        "10.10.10.0/24",
                        "10.10.20.0/24",
                        "10.10.30.0/24"
                    ],
                    "Providers": ["o365"],
                    "Clients":["webAppClient", "metatool", "appClient"]
                }
            ]
        }
    }
}

Migration des Gruppen- und Feldmappings

Das Gruppen- und Feldmapping wird nicht mehr beim CMI STS 3 konfiguriert, sondern über den Desktop Client direkt beim CMI. Die Migration erfolgt erst nach der Umstellung auf den CMI STS 3.

Migration des zweiten Faktors

Der zweite Faktor wird nicht mehr global konfiguriert, sondern bei ihren jeweiligen Mandanten. Der zweite Faktor muss für alle Benutzer im CMI zurückgesetzt werden (Feld: GoogleAuthKonfiguriert), daher Benutzer müssen ihren zweiten Faktor erneut einrichten. Das gilt auch, wenn das selbe Secret verwendet wird. Siehe auch im Kapitel Zweiter Faktor. Das selektive aktivieren des zweiten Faktors abhängig von IP-Adresse oder Client wird im CMI STS 3 mit sogenannten OTP Selektoren umgesetzt.

GoogleAuthKonfiguriert

CMI STS 2

{
    "SecondFactorGoogleAuth": {
      "Enabled": "true",
      "Secret": "...",
      "ClockDriftToleranceInSeconds": "300"
    }
}

CMI STS 3

{
    "Tenants": {
        "mandant1": {
            "Totp":
                {
                    "Secret": "..."
                }
        }
    }
}
CMI STS 2 CMI STS 3
Enabled Enabled
Secret Secret
ClockDriftToleranceInSeconds VerificationWindow
SecondFactorGoogleAuthEnabled OtpSelectors

Installation des CMI STS 3

Beide STS Versionen können nebeneinander installiert werden, jedoch nur einer von beiden kann die selbe URL verwenden. Wenn die alte STS URL beibehalten wird, ist an vielen Stellen keine Konfigurationsänderung erforderlich. Ausgenommen die Clients, die den Impersonation Grant verwenden. Sollte die Umstellung nicht klappen, kann im Notfall wieder die alte CMI STS 2 Installation auf die STS URL gebunden werden. Wenn der STS ausgetauscht wird, muss der CMI Server und alle Komponenten, die den CMI STS verwenden, neu gestartet werden.

Gruppen- und Feldmapping

Der CMI Server erkennt automatisch, ob der CMI STS 2 oder CMI STS 3 im Einsatz ist. Diese Information kann aus dem Discovery-Dokument (.well-known/openid-configuration) entnommen werden. Der CMI STS 3 teilt seine Versionsnummer über dieses Dokument mit.

Details sind im Kapitel IdentityProvider beschrieben.

Nicht interaktives Login mit dem Desktop Client

Der Desktop Client lässt sich mit einem nicht interaktiven Login-Verfahren starten:

.\cmi.client.main.exe -user=<Benutzername> -pw=<Passwort>

Desktop Client Version 21.X.X: Der Desktop Client führt eine Authentifizierung direkt beim CMI Server aus (BuiltIn-Login), ohne den CMI STS zu kontaktieren. Es wird kein Access-Token durch den CMI STS ausgestellt.

Desktop Client Version >=22.X.X: Der Desktop Clients kontaktiert den CMI STS auch, wenn ein nicht interaktives Login durchgeführt wird. Der Desktop Client versucht in diesem Fall ein Access-Token über den Password-Grant-Flow zu erhalten.

Wenn ein nicht interaktives Login ab dem Release 22 unterstützt werden soll, muss dazu ein Client mit dem Password-Grant-Flow der Konfiguration hinzugefügt werden (siehe Clients für ein Beispiel).