Zum Hauptinhalt springen

Upgrade auf iCL Portal 1.60+

iCL Portal 1.60 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.60 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.60 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.

Ä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" />

dox42-Host​

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