Skip to main content

Upgrading to iCL Portal 1.60+

iCL Portal 1.60 introduces several breaking changes and requires manual steps beyond the standard upgrade flow. Complete this guide before starting the normal upgrade (see Upgrading to newer versions).

Prerequisites​

.NET Framework 4.8​

The web front-end server must have .NET Framework 4.8 installed (required from iCL Portal 1.19.x onwards).

SQL Server 2017 or newer​

iCL Portal 1.60 requires SQL Server 2017 or newer and each iCL Portal database must use compatibility level 140 (or higher).

Run the following query against each iCL Portal database to verify:

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

Authentication changes​

Client credentials must be re-created​

iCL Portal 1.60 switches to a new authentication system (OpenIddict) to add OpenID support. Existing client credentials cannot be migrated because their secrets are stored encrypted.

After installing the new server version you must:

  1. Re-create every client credential in the user settings of the affected users.
  2. Distribute the new client IDs and secrets to every tool, integration or script that authenticates against iCL Portal.

Password grant is deprecated​

The OAuth 2.0 Password (Resource Owner) grant is deprecated. Move all consumers to the Client Credentials flow.

See the Auth API documentation for details.

WSFED / Azure Entra ID must be reconfigured​

Up to this version, WSFED or Azure Entra ID authentication could only be configured for a single tenant and only in web.config. That has changed — the configuration is now per-tenant and managed in the portal UI.

After the upgrade you must re-configure authentication:

  1. In iCL Portal — follow Configure the Azure Entra ID integration.
  2. In Azure Entra ID — review/update the corresponding App Registration (redirect URLs, client secret, etc.) to match the new per-tenant setup.

Salesforce authentication removed​

Salesforce authentication is deprecated and no longer supported. Customers previously using it must switch to another authentication provider (for example Azure Entra ID).

Data migrations​

migrate_databases.bat now runs data migrations in addition to schema migrations. These can take a long time on large tenants.

Schedule wisely

Run the upgrade on a Friday or outside office hours — not because the system goes down, but because the data migrations are noticeable.

The system stays operable

The system is already operable while the data migrations run. Users can continue to work while the migrations complete in the background.

web.config changes​

After extracting the new release package, update web.config as follows.

Target .NET Framework 4.8​

In <system.web>, ensure the <compilation> and <httpRuntime> elements target .NET 4.8:

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

Raise the query string length limit for JWT tokens​

JWT tokens can grow large enough to exceed the default IIS / ASP.NET query-string limits. Apply the following changes.

1. Update <requestFiltering> under <system.webServer>.

If no <requestLimits> element exists, add one:

<security>
    <requestFiltering>
        <requestLimits maxQueryString="32768" /> <!-- or another appropriate value -->
    </requestFiltering>
</security>

If a <requestLimits> element already exists, add the maxQueryString="32768" attribute to it. The resulting element should look like:

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

2. Update <httpRuntime>.

Add the attribute maxQueryStringLength="32768" to the existing <httpRuntime> element:

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

dox42 host​

iCL Portal 1.60 ships the dox42 report engine as a separate Windows service.