Zum Hauptinhalt springen

Upgrade auf iCL Portal 1.80+

iCL Portal 1.80 bringt mehrere tiefgreifende Änderungen mit sich und erfordert manuelle Schritte, die über den normalen Upgrade-Ablauf hinausgehen. Führen Sie diese Anleitung vor dem regulären Upgrade durch (siehe Neuere Versionen installieren).

Voraussetzungen​

.NET Framework 4.8​

Auf dem Server des Web-Frontends muss .NET Framework 4.8 installiert sein (erforderlich ab iCL Portal 1.19.x).

SQL Server 2017 oder neuer​

iCL Portal 1.80 erfordert SQL Server 2017 oder neuer und jede iCL-Portal-Datenbank muss Kompatibilitätsgrad 140 (oder höher) verwenden.

Führen Sie die folgende Abfrage gegen jede iCL-Portal-Datenbank aus, um dies zu überprüfen:

SELECT compatibility_level 
FROM sys.databases 
WHERE name = DB_NAME()

Änderungen an der Authentifizierung​

Client-Credentials müssen neu erstellt werden​

iCL Portal 1.80 wechselt auf ein neues Authentifizierungssystem (OpenIddict), um OpenID zu unterstützen. Bestehende Client-Credentials können nicht migriert werden, da ihre Secrets verschlüsselt gespeichert sind.

Nach der Installation der neuen Server-Version müssen Sie:

  1. Jede Client-Credential in den Benutzereinstellungen der betroffenen Benutzer neu anlegen.
  2. Die neuen Client-IDs und Secrets an alle Tools, Integrationen und Skripte verteilen, die sich gegen iCL Portal authentifizieren.

Der Password-Grant ist veraltet​

Der OAuth-2.0-Password-Grant (Resource Owner Password Credentials) ist veraltet. Stellen Sie alle Consumer auf den Client-Credentials-Flow um.

Details siehe Auth-API-Dokumentation.

WSFED / Azure Entra ID müssen neu konfiguriert werden​

Bis zu dieser Version konnte WSFED- oder Azure-Entra-ID-Authentifizierung nur für einen einzigen Tenant und nur in der web.config konfiguriert werden. Das hat sich geändert — die Konfiguration erfolgt nun pro Tenant und wird in der Portal-Oberfläche verwaltet.

Nach dem Upgrade müssen Sie die Authentifizierung neu konfigurieren:

  1. In iCL Portal — folgen Sie Azure Entra ID Integration konfigurieren.
  2. In Azure Entra ID — überprüfen bzw. aktualisieren Sie die zugehörige App-Registrierung (Redirect-URLs, Client-Secret usw.) entsprechend der neuen Konfiguration pro Tenant.

Salesforce-Authentifizierung entfernt​

Salesforce-Authentifizierung wird nicht mehr unterstützt und ist veraltet. Kunden, die sie bisher verwendet haben, müssen auf einen anderen Authentifizierungsanbieter umsteigen (z. B. Azure Entra ID).

Datenmigrationen​

migrate_databases.bat führt nun zusätzlich zu den Schema-Migrationen auch Datenmigrationen aus. Diese können bei großen Mandanten (Tenants) lange dauern.

Zeitpunkt sinnvoll wählen

Führen Sie das Upgrade am Freitag oder außerhalb der Bürozeiten durch — nicht weil das System ausfällt, sondern weil die Datenmigrationen spürbar sind.

Das System bleibt verwendbar

Das System ist bereits betriebsbereit, während die Datenmigrationen laufen. Benutzer können weiterarbeiten, während die Migrationen im Hintergrund abgeschlossen werden.

Migrator bricht mit „The COMMIT TRANSACTION request has no corresponding BEGIN TRANSACTION“ ab​

Bricht migrate_databases.bat mit

Unhandled Exception: System.Transactions.TransactionAbortedException: The transaction has aborted. ---> System.Data.SqlClient.SqlException: The COMMIT TRANSACTION request has no corresponding BEGIN TRANSACTION.

ab, starten Sie den Migrator direkt und übergeben Sie ihm den Connection-String Default aus der web.config als Argument. Öffnen Sie dazu eine Eingabeaufforderung im Ordner des iCL Portals (z. B. C:\inetpub\wwwroot\iCLPortal) und führen Sie aus:

bin\icl.portal.migrator.exe "Server=.;Database=portal;Trusted_Connection=True;TrustServerCertificate=True;"

Ersetzen Sie den Connection-String durch den Wert von Default aus Ihrer web.config und führen Sie den Befehl mit demselben Windows-Benutzer aus, mit dem Sie auch migrate_databases.bat ausführen würden.

Ohne Argument liest der Migrator die web.config und migriert die Host-Datenbank auf eine Weise, bei der der eigentliche SQL-Fehler hinter der obigen Meldung verborgen bleibt. Mit einem Connection-String als Argument wird die web.config nicht gelesen, die Migrationen laufen normal und ein tatsächlicher Fehler wird angezeigt.

Hinweis

In diesem Modus ändert der Migrator die web.config nicht. Stellen Sie sicher, dass der Connection-String Default TrustServerCertificate enthält, wie unter Dem SQL-Server-Zertifikat vertrauen beschrieben.

Änderungen an der web.config​

Nach dem Entpacken des neuen Release-Pakets muss die web.config wie folgt angepasst werden.

.NET Framework 4.8 als Zielplattform​

Stellen Sie in <system.web> sicher, dass <compilation> und <httpRuntime> auf .NET 4.8 abzielen:

<compilation targetFramework="4.8" debug="false">
  <assemblies>
    <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
  </assemblies>
</compilation>
<httpRuntime targetFramework="4.8" maxRequestLength="51200" executionTimeout="300" />

Query-String-Länge für JWT-Tokens erhöhen​

JWT-Tokens können so groß werden, dass die Standard-Limits von IIS / ASP.NET für Query-Strings überschritten werden. Nehmen Sie die folgenden Änderungen vor.

1. <requestFiltering> unter <system.webServer> anpassen.

Falls kein <requestLimits>-Element existiert, fügen Sie eines hinzu:

<security>
    <requestFiltering>
        <requestLimits maxQueryString="32768" /> <!-- oder ein anderer geeigneter Wert -->
    </requestFiltering>
</security>

Falls bereits ein <requestLimits>-Element existiert, fügen Sie lediglich das Attribut maxQueryString="32768" hinzu. Das Ergebnis sollte so aussehen:

<security>
  <requestFiltering>
    <requestLimits maxAllowedContentLength="52428800" maxQueryString="32768" />
  </requestFiltering>
</security>

2. <httpRuntime> anpassen.

Fügen Sie dem bestehenden <httpRuntime>-Element das Attribut maxQueryStringLength="32768" hinzu:

<httpRuntime targetFramework="4.8"
             maxRequestLength="51200"
             executionTimeout="300"
             maxQueryStringLength="32768" />

Dem SQL-Server-Zertifikat vertrauen​

Teile des Portals verbinden sich nun standardmäßig verschlüsselt mit dem SQL Server. Verwendet der SQL Server ein selbstsigniertes Zertifikat (der Standard bei einer On-Premises-Installation), schlagen diese Verbindungen mit „Die Zertifikatkette wurde von einer nicht vertrauenswürdigen Zertifizierungsstelle ausgestellt“ fehl.

Hängen Sie ;TrustServerCertificate=True; an den Connection-String Default unter <connectionStrings> an:

<connectionStrings>
  <add name="Default"
       connectionString="Server=.;Database=portal;Trusted_Connection=True;TrustServerCertificate=True;"
       providerName="System.Data.SqlClient" />
</connectionStrings>
Hinweis

Enthält der Connection-String bereits TrustServerCertificate — etwa TrustServerCertificate=False für eine Azure-SQL-Datenbank mit vertrauenswürdigem Zertifikat —, lassen Sie ihn unverändert.

dox42-Host​

iCL Portal 1.80 liefert die dox42-Berichts-Engine als eigenständigen Windows-Dienst aus.