Installation
2 Installing iCL Portal (single server)
The following sections describe the installation process for all required components of the iCL System. It is recommended to install the components in the order of this manual.
2.1 Installing the back-end
Install all required software as listed in 1.4
Create a new database for iCL Portal in SQL Management Studio
Run the following script to ensure, that Snapshot Isolation is enabled on the database
DECLARE @databaseName sysname;
SET @databaseName = (SELECT db_name());
DECLARE @SQL varchar(1000);
SET @SQL = 'IF EXISTS (SELECT NAME FROM sys.databases where NAME = N'''+@databaseName+''' AND [snapshot_isolation_state] = 0)
BEGIN
ALTER DATABASE ['+@databaseName+'] SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE ['+@databaseName+'] SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE
END'
Exec (@SQL)Note the connection string to the database.
2.2 Installing the web front-end
Install all required software as listed in 1.4
Create a new IIS Web-Site
Make sure that the application pool that was created for this site runs .NET 4.0
Copy all files from the web-frontend folder into the root folder of your website. In this example this would be:
In this screenshot you can see the two important configuration files for adapting the iCL Portal web-frontend: the NLog.config and the Web.config file.c:\inetpub\icl_portal.Make sure that the user that runs the application pool has full access to the
App_Datafolder as this is the default location for storing all files and logs.For this, find out the name application pool that iCL Portal runs on. In this example iClPortalAppPool. Then open the security settings of the
App_Datafolder and add the application pool user with full access. As username, useIIS AppPool\apppoolname, soIIS AppPool\iClPortalAppPoolin this example. Do not click on search or check names as these will not find this special user!Stop the website so you can configure the portal for the first start:
Configure the bindings of the web front-end and make sure that there exists an HTTPS binding that is secured with a trusted certificate.
noteIn production environments, only HTTPS connections are supported as the system might be compromised otherwise!
noteIf you created a separate database for the background job storage, make sure that on the server that runs the iCL Portal web front-end, the service
Distributed Transaction Coordinatoris running and has the starttypeAutomatic:noteThe default web.config of iCL Portal comes with a default machineKey which is used to encrypt tokens for email-verification and password recovery. This machineKey must be the same on all web front-ends! We strongly encourage you to create your own machine keys. For a manuall, see here.
2.3 Configuring web front-end
The fundamental configuration of the iCL Portal Web Front-end is done by editing the Web.config.
If you start out with a clean install, download Web.config template from here Copy the file into the root folder of iCL Portal and rename it to Web.config.
Open Web.config in your favorite text editor and navigate to the <appSettings> element. This node contains all relevant configuration options.
2.3.1 Configure your icl portal key
Search for the element with the key License.Key and specify there the license key, that you got when you purchased iCL Portal:
<add key="License.Key" value="" />
2.3.2 Configure connection to sql server database:
iCL Portal has two logically separate databases whose connections can be specified in the <connectionStrings> element:
<connectionStrings>
<add name="Default" connectionString="Data Source=SERVERNAME\INSTANCENAME;Initial Catalog=DATABASENAME;Integrated Security=True" providerName="System.Data.SqlClient" />
</connectionStrings>`
The Default connection is the one that stores all relational data of the iCL System.
For single server installations, ensure that you create a login for the application pool user.
Add a login for the user IIS AppPool\apppoolname - in our example: IIS AppPool\iClPortalAppPool
Do not click search as this will resolve an invalid user!
iCL Portal manages the schema of the database and migrations itself: migrate_databases.bat creates all required tables, views, stored procedures, etc. (see 2.3.8). The portal no longer creates them on its first start. Therefore it requires db_owner permissions for both databases! With integrated security, migrate_databases.bat connects as the Windows user that runs it, so this user needs db_owner permissions, too.
The connectionString attribute requires a ADO.NET connection string. The following example shows the configuration with a database Portal on a named MSSQL Instance SQLSERVER on a machine called SQL using integrated security.
<connectionStrings>
<add name="Default" connectionString="Data Source=SQL\SQLSERVER;Initial Catalog =Portal; Integrated Security=True;" providerName="System.Data.SqlClient" />
</connectionStrings>
The following example uses SQL server security with USERNAME and PASSWORD.
<connectionStrings>
<add name="Default" connectionString="Data Source=SQL\SQLSERVER;Initial Catalog =Portal; User ID=USERNAME;Password=PASSWORD;" providerName="System.Data.SqlClient" />
</connectionStrings>
The following example specifies a non-default port 1234.
<connectionStrings>
<add name="Default" connectionString="Data Source=SQL\SQLSERVER,1234;Initial Catalog =Portal; User ID=USERNAME;Password=PASSWORD;" providerName="System.Data.SqlClient" />
</connectionStrings>
2.3.3 Configure file storage
By default, iCL Portal stores all files in its APP_DATA folder. To change this setting,
- find the configuration element with the key
FileBlobStorageRoot:
<add key="FileBlobStorageRoot" value="~/App_Data" />
- Specify data-folder that will contain all files like reports, workbooks, pictures, etc. This can of course be a network path. E.g.:
<add key="FileBlobStorageRoot" value="\\FILESERVER\ICLPortalFiles" />
- Make sure that the user that runs the application pool has full access to this folder
2.3.4 Configure smtp server
iCL Portal Web front-end uses the SMTP server for sending mails for password recovery and account confirmation.
Reports, however, are being sent by the dox42 Server directly.
By default, iCL Portal expects the SMTP server to be running locally on a web front-end on port 25.
In order to change this, open the web.config and find the <mailSettings> element.
<system.net>
<mailSettings>
<smtp deliveryMethod="Network" from=`noreply@iclportal.com`>
<network host="localhost" port="25" defaultCredentials="true" />
</smtp>
</mailSettings>
</system.net>
The following example shows how to provide username and password and specify a default from-address and enable SSL encryption:
<system.net>
<mailSettings>
<smtp deliveryMethod="Network" from="noreply@mycorp.com">
<network defaultCredentials="false" host="smtp.mycorp.com" port="587" userName="mailuser@mycorp.com" password="somepassword" enableSsl=`true`/>
</smtp>
</mailSettings>
</system.net>
The syntax of the network element as documented here
<network
clientDomain="string"
defaultCredentials="true|false"
enableSsl="true|false"
host="string"
password="string"
port="integer"
targetName="string"
userName="string"
/>
2.3.5 Remote diagnostics
iCL Portal has remote diagnostics enabled by default. These send non-confidential informations such as occurred exceptions and stack traces to a central service hosted by Opti-Q.
Therefore configure the firewall of the iCL Portal Web-frontend to allow outgoing connections on port 443. Otherwise we will not receive any diagnostic information.
The setting with key iKey in the <appSettings> element contains the api key required to access this service.
Do not change the iKey unless advised so by an Opti-Q staff member, otherwise we cannot provide full support.
Also, there exists an additional element <applicationinsights.tags> which contains additional metadata that is transmitted to our service to be able to identify our customer and the environment (dev/staging/production)
<applicationinsights.tags>
<add key="customer" value="yourcompanyname" />
<add key="environment" value="production" />
</applicationinsights.tags>
2.3.6 Configure logging by editing nlog.config
iCL Portal uses NLog to log diagnostics information to the local file system. This logging mechanism is buffered to ensure a minimum performance impact so do not expect log messages to appear instantly. By default, logfiles are written to the web front-ends APP_DATA folder.
If you do not yet have an NLog.config file in your web front-end create an NLog.config file with these contents in the root folder of iCL Portal.
To change logging, NLog.config in your favorite text editor
- By default, Nlog is creating its logs files in the local App_Data folder. To change this, edit the paths that start with
${basedir}\App_Datato point to your desired folder location. Note that absolute paths are also supported.noteChanges of the NLog.config should take effect almost immediately. Do not recycle the application pool or restart IIS!
- By default, NLog is configured to log only messages on WARN level. If you want to configure a more verbose logging, open the NLog.config and change the following line
<logger name="*" minlevel="Warn" writeTo="Trace" />
to
<logger name="*" minlevel="Debug" writeTo="Trace" />
- External logins (Microsoft Entra ID and OpenID Connect providers) are written to a file of their own,
<date>_externallogin.log(NLog targetExternalLogin), see External login log. An existing NLog.config is kept when you upgrade iCL Portal: if yours does not contain the targetExternalLoginyet, copy the target and the three<logger>rules forExternalLoginandOpenIddictfrom the NLog.config template. Without them, only errors of external logins are logged (in the error log).
2.3.7 Configuring additional plugins
iCL Portal allows to create plugins to integrate with your corporate systems. In case we developed a plugin for you, you will get a separate package with installation instructions.
These most of the time only consist of copying some additional dlls into the bin directory of your iCL Portal web front-ends and adding another appSettings element to your Web.config.
2.3.8 Start the icl portal website
Once all configuration is done, run migrate_databases.bat in the root folder of the website and confirm with Y. It creates all required tables, views, stored procedures, etc. in the database. This step is required: a fresh installation no longer creates its database when it starts for the first time.
Then start up the iCL Portal website and finish last couple of configuration steps with your favorite browser.
2.3.9 System/Host configuration
iCL Portal supports multi tenancy. To manage tenants, you need to login as host admin. During the setup, a single host admin - which belongs to no tenant - is created with a default password. To secure your system, it is absolutely necessary to login with this user and change his password.
To do this, login by leaving the tenant textbox empty and use the username admin with the default password 123qwe
Logged in as host admin, you have to configure the iCL Portal license key. To do this, navigate to settings and in the category "general" you will find the license id textbox:
Enter the license key (e.g.: 327d75a8-64b5-49ac-bf90-2544229dbeca) that you got from Opti-Q and click on save.
2.3.10 Create tenant
iCL Portal supports having multiple tenants, each with its completely isolated environment. To run the portal, a default tenant is required.
To do so, navigate to Settings/Tenants and click CREATE to create a new one. Make sure, that the tenancy name only consists of letters, then hit CREATE again
Then, a new tenant will be created for you with a default administrator for this tenant. This may take a minute or two.
2.3.11 Configuring the new tenant
To login to this tenant, first logout as host admin in the upper right corner
and navigate back to the login screenAt the Login screen, login using the tenancy name you just created (contoso in this example) the username admin and the default password 123qwe
Once logged in, immediately change this password to a strong one using the menu in the upper left corner:
Thereafter, you can go to
SETTINGS/USERSand create as many users for this tenant as you like.Finally upload your license files in SETTINGS/LICENSES by dragging and dropping the files into the list one by one
2.3.12 Logging in on a tenant URL
A tenant can have its own URL, e.g. one subdomain per tenant. To set it up, login as host admin, navigate to Settings/Tenants, edit the tenant and enter a Url pattern: a regular expression that is matched against the full URL of each request, e.g. ^https://contoso\.portal\.example\.com
When the login page is opened on a URL that matches the Url pattern of a tenant:
- the tenant field is prefilled with this tenant (it can still be changed),
- the external login providers of this tenant are listed, and an external login logs the user in to this tenant.
Below the prefilled tenant field, the link Switch to host clears the field. An empty tenant field means the host: the external login providers of the host are listed, and both the password login and the external login log the user in to the host. Clearing the field by hand has the same effect.
The switch only lasts for the browser session (the session cookie iCL.HostLogin is set). The next time the login page is opened, the tenant of the URL is prefilled again.
The link is not shown when iCL Filler asks the user to login again, because the app sets the user name and tenant.
If you use one host name per tenant together with an external login provider or iCL Filler 3, also see One host name per tenant.
2.4 Configure the Azure Entra ID integration (optional)
iCL Portal authenticates users itself (user name and password). In addition, you can add an external login provider. This allows your users to login using one click, instead of typing in their passwords. Since iCL Portal 1.80, external login uses OpenID Connect. The supported external providers are Microsoft Entra ID (this section) and any other OpenID Connect provider, e.g. IBM Verify Identity Access or Keycloak (see Configure a generic OpenID Connect provider). Both can be configured side by side. (Before version 1.80, it used WS-Federation configured in the web.config, see Upgrading to iCL Portal 1.80+.)
Once you configured the Azure Entra ID integration correctly, users will see it listed as external login provider:
Under the hood, iCL Portal will only authenticate the user using Azure Entra ID. As soon as Azure Entra ID redirects the user back to iCL Portal a new user will be created in the database and is assigned the default role that you defined. For the iCL Portal administrator that assigns users to roles and teams, users coming from Azure Entra ID will look identical to users coming from iCL Portal and they are also handled the same way.
2.4.1 Creating an app registration in Azure Portal
To set up Azure Entra ID as external authentication provider, we first must tell Azure Entra ID, that our iCL Portal application exists and is allowed to use Azure Entra ID to authenticate users.
For this, go to https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps and create new app registration.
For the sake of giving an example, we will configure an app registration using the FQDN of our test system: https://testportal.opti-q.com/callback/login/microsoft (Replace this with the FQDN of your iCL Portal installation) and ensure that you add /callback/login/microsoft at the end.
If your users reach iCL Portal under several host names (e.g. one per tenant), add such a redirect URI for each of them, see One host name per tenant.
Once that is done, opent he app registration and copy the client-id, tenant-id and a client secret (you will have to create a new client secret for this) and save it for the next step.
Now, login to iCL Portal as administrator and naviate to settings / Open ID: Microsoft Entra ID There, enter the client-id, tenant-id and client-secret that you copied in the previous step and click on save.
A provider is configured either for one tenant or for the host:
- Logged in to a tenant as its administrator, you configure the provider of this tenant (settings
tenant.openid.authproviders.microsoft.*). - Logged in as host admin, you configure the provider of the host (settings
application.openid.authproviders.microsoft.*). Tenants do not inherit it; it is only used for host users.
A provider is only listed on the login page of the tenant it is configured for (or of the host, if the tenant field is empty). A login with a provider of another tenant fails. Which tenant the login page uses is described in Logging in on a tenant URL.
Other options you can set are:
Display name: This will be shown to your users in the login screen, so you can set it to whatever you like. E.g. "Login with Azure Entra ID"
Additional scopes: lets you define additional scopes/claims that will be requested from Entra ID
Email/Name/Surname/Username Claim Type: allows you to override which claims are used for the e-mail address, first name, last name and user name of the user. Usually you do not need to touch this. That is only for advanced use cases. The defaults are:
Setting Default claim type Email Claim Type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressName Claim Type (first name) http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameSurname Claim Type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameUsername Claim Type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameIf you would like to use the value of some other claim as username, define it using the Username Claim Type setting. (The Name Claim Type sets the first name of the user.)
The claim is optionalAs opposed to the External ID Claim Type, the presence of the username claim is optional. If a user authenticates and the corresponding token does not contain this claim, the system falls back to using the e-mail address of the user as username.
External ID Claim Type: Use this if you want to define a claim that is used as reference/external ID for the user. It can be used to map an existing Entra ID claim to the
ExternalId/Referenceof a user, e.g. the Object ID of the user. By default, this setting is empty: no external ID is used. To find out which claims your provider sends, see Debugging the claims. The value of the claim is stored in the field Reference of the iCL Portal user:If set, the defined claim is requiredWhen this setting is set, every user token must contain this claim. Otherwise a new user cannot be registered.
noteYou can use this to create users in iCL Portal upfront and assign them to teams or give them global roles. Once the user logs in with their Azure Entra ID account, they will take over the iCL Portal user. The easier solution, though, is just enabling the setting Match users by e-mail
Whether the properties of the Entra ID user (e-mail, first name, last name) are applied to the iCL Portal user every time the user logs in is controlled by the setting Update user properties.
Match users by e-mail: if disabled and a local user is found that has the same e-mail address, the system returns an error. If enabled, it allows the user to "take over" the existing user profile. (Default: disabled)
Implicitly register users: if enabled and the user does not yet exist locally, a local user account will be created and the default roles assigned. If disabled, the user is shown a registration form instead, to check his/her name, username and e-mail address. (Default: enabled)
Default roles: The roles (separated by comma) that will be given to a new implicitly registered user (Default:
User; an empty value also meansUser)Update user properties: If enabled, whenever a user logs in from Entra ID, the properties (first name, last name, e-mail and username) will be updated to the values provided by Entra ID. This is especially useful if you have enabled implicit registration and want to ensure that the user properties are always up to date with the values in Entra ID. (Default: enabled)
Access script: an optional JavaScript that decides on every login whether the user may log in, and which roles a newly registered user gets, see Access script. (Default: a template that admits everybody)
2.4.2 Required claims
As already noted, when the users login using an external authentication provider, iCL Portal implicitly creates a local user profile for them which can then be used by local iCL Portal administrators in order to assign roles to them or make them members of a team. To create users, a minimal set of claims has to be provided by the authentication provider. These three claims are:
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress which will be used as his/her email address (and as username, if the token does not contain the username claim).
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname which will be set as the users first name
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname which will be set as the users last name
These are the default claim types; you can change them in the settings described above.
If one of them is missing, the user is not registered implicitly. Instead, a registration form asks the user for the missing values.
As for Azure Entra ID, these are the properties of a user that have to be set:
2.4.3 Debugging the claims
To see which claims an external login provider (Microsoft Entra ID or an OpenID Connect provider) sends for a user (e.g. to choose one of the claim types above, or to write an access script):
- Enable the setting Enable claim debugging (
openid.authproviders.enableClaimsDebugging) in the settings group OpenID: as host admin for the provider of the host, as administrator of a tenant for the provider of this tenant. - In your browser, open the developer tools (F12) and add a cookie named
Abp.ShowClaimswith any value for the iCL Portal site (Application → Cookies). - Login with the external login provider. Instead of logging the user in, iCL Portal shows all claims it received (claim type and value).
- When you are done, delete the cookie and disable the setting again.
The claims are shown before the access script runs, so this also works for a user the script denies. The output can be pasted as it is into the Test script dialog of the access script.
In addition, while the setting is enabled, every external login writes the received claims (type and value) to the external login log. Without it, the log only names the claim types.
2.4.4 One host name per tenant
If each tenant has its own host name (see Logging in on a tenant URL), e.g. https://contoso.portal.example.com and https://fabrikam.portal.example.com:
TLS certificate: the certificate of the IIS web site must cover all host names.
Redirect URIs: in the app registration of the external login provider, add a redirect URI for every host name the provider is used on:
https://<tenant host>/callback/login/microsoftfor Microsoft Entra ID,https://<tenant host>/callback/login/oidcfor an OpenID Connect provider.iCL Filler 3: by default, the issuer of the OpenID Connect server of iCL Portal (used by iCL Filler 3, iCL Designer and API clients) is the
Abp.PublicUrlfrom the web.config. iCL Filler 3 only accepts an issuer that is equal to the server URL the user entered. If your users enter a tenant host name as server URL in iCL Filler 3, login as host admin, navigate to Settings, group OpenID, and enable Issuer follows the request host. It takes effect without a restart. The default of this setting comes from theappSettingsof the web.config:<add key="openid.authproviders.server.issuerFromRequest" value="true" />The issuer then follows the host name of each request.
caution- Tokens are only valid on the host name they were issued on.
- Apps that already use the host name from
Abp.PublicUrlkeep working; apps can now also use the tenant host names as server URL. Abp.PublicUrlstays the base of the links in e-mails (one URL for all tenants).
2.5 Configure a generic OpenID Connect provider (optional)
Besides Microsoft Entra ID, iCL Portal can use any identity provider (IdP) that supports OpenID Connect, e.g. IBM Verify Identity Access, Keycloak or Okta. The provider is listed on the login page next to the other login options, with the display name you configure:
The user is registered or matched exactly as described for Microsoft Entra ID in Configure the Azure Entra ID integration, and the same rules apply for host and tenants: logged in to a tenant as its administrator, you configure the provider of this tenant (settings tenant.openid.authproviders.oidc.*); logged in as host admin, you configure the provider of the host (settings application.openid.authproviders.oidc.*). Tenants do not inherit the provider of the host. Each tenant (and the host) can have one OpenID Connect provider in addition to Microsoft Entra ID.
2.5.1 Prerequisites at the identity provider
Register iCL Portal as a client (application) at your identity provider. The provider and the client must support:
- OpenID Connect with an
id_token(not plain OAuth 2.0), - the authorization code flow with a client secret (confidential client),
- an
id_tokensigned with RS256; the signing keys are published as JWKS (jwks_uriin the discovery document), - a discovery document (OpenID Connect metadata). Its
issuermust be exactly the issuer you configure in iCL Portal. - Client authentication at the token endpoint: iCL Portal sends the client secret as
client_secret_basicorclient_secret_post, as the discovery document advertises intoken_endpoint_auth_methods_supported. If the discovery document does not advertise any method,client_secret_basicis used, so the client must accept it.
Register this redirect URI in the client, once for every host name your users use to reach iCL Portal (see One host name per tenant):
https://<portal host>/callback/login/oidc
Note the client id and the client secret for the next step.
Apart from the browser of the user, the iCL Portal server itself calls the identity provider: it reads the discovery document and the JWKS, and it exchanges the authorization code for the tokens at the token endpoint. Make sure that
- these endpoints are reachable from every iCL Portal web front-end (firewall, proxy) without a login,
- the TLS certificate of the identity provider is trusted by the Windows servers of iCL Portal.
If the identity provider cannot be reached, the user gets a failure page "The login provider is currently not available" (after up to a minute, as the server retries first), and the cause is written to the external login log.
2.5.2 Settings
Login to iCL Portal as administrator (of the tenant, or as host admin for the host) and navigate to Settings, group OpenID Connect (below OpenID: Microsoft Entra ID). Enter at least the issuer, the client ID and the client secret, and save each setting. Changes take effect immediately, without a restart.
The provider is enabled as soon as Issuer and Client ID are set. If only one of them is set, or a value is not an absolute URL, the provider is not offered and an error is written to the log.
| Setting | Default | Description |
|---|---|---|
| Display name | OpenID Connect | The name shown on the login page, e.g. "Company login". |
| Issuer | The issuer of the identity provider, e.g. https://idp.example.com. It must be exactly the issuer in its discovery document (the id_tokens are checked against it). | |
| Discovery URL | Optional. Only needed if the identity provider does not publish its discovery document at {issuer}/.well-known/openid-configuration. E.g. IBM Verify Identity Access publishes it at https://<host>/mga/sps/oauth/oauth20/metadata/<definition> (the exact path depends on the configuration of the identity provider). | |
| Client ID | The client id registered for iCL Portal at the identity provider. | |
| Client secret | The client secret of this client. It is shown masked. | |
| Scopes | openid profile email | The scopes requested from the identity provider, separated by spaces. Add the scope that adds the claims you need, e.g. groups, if your identity provider requires one. |
| Email / Name / Surname / Username Claim Type | as for Entra ID | Which claims are used for the e-mail address, first name, last name and user name, see the defaults and Claims below. |
| External ID Claim type | As for Microsoft Entra ID. E.g. sub to store the user id of the identity provider as Reference. | |
| Match users by e-mail | disabled | As for Microsoft Entra ID. |
| Implicitly register users | enabled | As for Microsoft Entra ID. |
| Default roles | User | The roles (separated by comma) of an implicitly registered user. Empty means no roles: the user can log in, but sees nothing until an administrator assigns roles or teams. (Unlike Microsoft Entra ID, where empty means User.) An access script can replace them. |
| Update user properties | enabled | As for Microsoft Entra ID. |
| Access script | template | Optional JavaScript that decides whether the user may log in and which roles a new user gets, see Access script. |
2.5.3 Claims
OpenID Connect providers send the standard claims email, given_name, family_name, preferred_username and sub. iCL Portal adds the corresponding WS-Federation claim types next to them, so the default claim type settings work without changes:
| Claim of the identity provider | Added claim type | Used by default for |
|---|---|---|
email | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | Email Claim Type |
given_name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | Name Claim Type (first name) |
family_name | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | Surname Claim Type |
preferred_username | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | Username Claim Type |
sub | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
Other claims keep their names. A claim that is a JSON array in the id_token, e.g. "groups": ["users", "portal-contoso"], arrives as several claims of the same type, one per value. If a required claim is missing, the user gets the registration form instead (see Required claims). To see what your identity provider actually sends, use Debugging the claims; it works for both providers.
2.6 Access script (optional)
An access script is a small JavaScript that runs on every login with an external login provider. It decides whether the user may log in to this tenant (or the host), and which roles a user gets who is registered by this login, e.g. based on the groups the identity provider sends. Every external login provider has its own access script: the setting Access script in the settings group OpenID Connect and in OpenID: Microsoft Entra ID.
Without an access script, every user who can log in at the identity provider can log in to iCL Portal. By default, the setting contains a commented template. As long as the template is unchanged (or the setting is empty), the login is not restricted and the script is not run. Reset to default brings the template back.
2.6.1 How it works
The script must define this function:
function checkAccess(claims, tenant) {
return { allow: true, roles: ['User'] };
}
claims: the claims of the user, as an object with one property per claim type (see below).tenant: the tenancy name of the login,nullfor the host.- It returns an object with
allow:trueadmits the user,falsedenies the login,roles(optional): the roles of a user who is registered now.
The script runs on every login with this provider, also when the user submits the registration form (if implicit registration is disabled). If it returns allow: false, throws an error, does not return a valid object or exceeds a limit, the login is denied. The user sees a failure page with a reference for the administrator (see Troubleshooting external logins). Removing a user from a group at the identity provider therefore locks him or her out on the next login.
Roles: the result decides the roles only when the user is registered by this login (implicitly or through the registration form) or linked to an existing user for the first time (e.g. by Match users by e-mail):
| Result | Roles |
|---|---|
{ allow: true } (no roles) | the configured Default roles |
{ allow: true, roles: ['Admin', 'User'] } | these roles, instead of the default roles |
{ allow: true, roles: [] } | no roles |
On later logins, the roles are not changed: change them in iCL Portal. Role names are case-sensitive and must exist in the tenant (or the host). If a role does not exist, the registration fails.
2.6.2 The claims object
claims contains the claims as claims debugging shows them, including the claim types iCL Portal adds (see Claims). A claim type sent once is a string, a claim type sent several times is an array. Use [].concat(...) to handle both, e.g. a user in only one group:
var groups = [].concat(claims.groups || []); // always an array, also with one or no group
This also applies to claims you would not expect: e.g. Keycloak sends email_verified both in the id_token and from the userinfo endpoint, so it is an array ["true", "True"]. All values are strings.
A shortened example of the claims of a login with an OpenID Connect provider:
{
"iss": "https://idp.example.com",
"aud": "icl-portal",
"sub": "2f6c1d0e-7a4b-4c39-9e1a-5b8d3f2a6c71",
"email_verified": ["true", "True"],
"name": "Jane Doe",
"groups": ["users", "portal-contoso", "portal-admins"],
"preferred_username": "jdoe",
"given_name": "Jane",
"family_name": "Doe",
"email": "jane.doe@example.com",
"oi_prvd_name": "Oidc__contoso",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname": "Jane",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname": "Doe",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "jane.doe@example.com",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "jdoe",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "2f6c1d0e-7a4b-4c39-9e1a-5b8d3f2a6c71"
}
2.6.3 Limits
The script runs on the iCL Portal server (JavaScript engine Jint), without access to the network, files or .NET. To protect the server, it is stopped, and the login denied, when it
- runs longer than 2 seconds,
- calls functions deeper than 200 levels (recursion),
- executes more than 1,000,000 statements,
- allocates more than 32 MB of memory.
2.6.4 Testing the script
Click Test script… below the description of the setting. The dialog runs the script exactly as a login would (same engine, same limits). Nothing is saved and no user is created.
- Tenancy name: passed to
checkAccessastenant(only for the host admin; empty means the host). Logged in to a tenant, the script is tested for your tenant. - Claims: paste an
id_token(JWT; the signature is not checked), a JSON object of claims (e.g. the decoded id_token payload) or the output of claims debugging. For an id_token or a JSON object, the dialog adds the claim types iCL Portal adds at login (see Claims). - Script: taken from the editor, including unsaved changes. Save the setting to use it at login.
Run shows whether access is allowed, and which roles a user registered with this result gets. If a role does not exist in the tenant, the dialog warns: a real registration would fail. Claims passed to the script shows the claims object the script got.
An error in the script denies the login; the dialog shows the message with line and column:
Copy for browser console copies claims, tenant, script and the call as one snippet. Paste it into the developer console of your browser (F12 > Console) to debug the script with breakpoints. There is no time limit there, and in rare edge cases the browser and the script engine of iCL Portal behave differently: check the result with Run.
2.6.5 Examples
One group per tenant: only members of the group portal-<tenancy name> may log in to a tenant; members of portal-admins become administrators, all others users.
function checkAccess(claims, tenant) {
var groups = [].concat(claims.groups || []);
if (groups.indexOf('portal-' + tenant) < 0)
return { allow: false };
if (groups.indexOf('portal-admins') >= 0)
return { allow: true, roles: ['Admin'] };
return { allow: true, roles: ['User'] };
}
For the host (tenant is null), use a separate group, e.g. if (tenant === null) return { allow: groups.indexOf('portal-host') >= 0 };.
Only some e-mail domains, no roles for new users (an administrator assigns them):
function checkAccess(claims, tenant) {
var email = (claims.email || '').toLowerCase();
return { allow: /@(example\.com|example\.org)$/.test(email), roles: [] };
}
Microsoft Entra ID app roles: define app roles in the app registration and assign users or groups to them. Entra ID sends them in the claim roles:
function checkAccess(claims, tenant) {
var appRoles = [].concat(claims.roles || []);
if (appRoles.indexOf('Portal.Admin') >= 0)
return { allow: true, roles: ['Admin'] };
return { allow: appRoles.indexOf('Portal.User') >= 0 };
}
Entra ID only sends the claim groups if the groups claim is configured in the app registration (Token configuration), and then it contains the object IDs of the groups, not their names. App roles are usually easier to use. Check with claims debugging what your app registration sends.
2.7 Troubleshooting external logins
If an external login fails, the user sees a failure page with a short reason and a reference (and the time in UTC):
E.g. "You do not have access to this Portal" means that the access script denied the login; "The login provider is currently not available" means that the discovery document or the JWKS of the identity provider could not be loaded. Search the external login log for the reference to find the cause.
2.7.1 External login log
Every external login (Microsoft Entra ID and OpenID Connect providers) is written to its own log file in the log folder of iCL Portal (by default App_Data\Logs):
App_Data\Logs\<date>_externallogin.log
It is written by the NLog target ExternalLogin (see Configure logging) and contains one line per step: the redirect to the provider, the callback (with the claim types received and the approximate size of the claims), the tenant check, the result of the access script, the sign-in, and the registration or linking of the user, together with the errors of the OpenID Connect client (discovery document, issuer, token endpoint). Each line starts with a correlation id in brackets, e.g. [ca50906d]. The correlation id of the lines of the login is the reference shown on the failure page; the callback line just before has its own id.
- The log names the claim types only. The claim values (personal data) and, for a login denied by the access script, a snippet to debug the script in the browser console are only written while claims debugging is enabled.
- Tokens, authorization codes and client secrets are never written to the log; user ids appear as a fingerprint (e.g.
#3f2a9c1b). - If the claims of a user are larger than about 3,000 bytes (e.g. many groups), a warning is logged: browsers can reject such large cookies.
If a login is rejected without a clear reason in the log (e.g. a problem with the id_token), set the level of the OpenIddict client to Debug in the NLog.config for a while:
<logger name="OpenIddict.Client*" minlevel="Debug" writeTo="ExternalLogin" />
The line ... was marked as rejected by OpenIddict.Client.OpenIddictClientHandlers+<check> then names the check that failed. Set it back to Info afterwards.
2.8 Installing the dox42 host
iCL Portal generates dox42-based reports in a separate Windows service (iCLPortalDox42) so that long-running report jobs do not impact the web front-end. The service shares the same SQL Server database as iCL Portal (for Hangfire job dispatch).
2.8.0 Where to install the service
The service is a box of its own in the architecture diagrams and you can place it either way:
- On the iCL Portal machine. The service reads the ICLR files through the same local file system path that the web front-end uses (
FileBlobStorageRoot, see 2.3.3). No share is needed — just enter that same local path when the wizard asks for the storage. - On a separate server/VM. The storage must then be reachable from both machines, so it has to be a UNC network share (for example
\\FILESERVER\ICLPortalFiles) that is configured asFileBlobStorageRootin the web front-end and as the storage path of the dox42 service.
A local account cannot access a network share. If the service runs on a separate machine, give it a domain account (or a machine account that is permitted on the file server) with full access to the share, and enter that account as the service account in the wizard. The default NT AUTHORITY\NetworkService only works when the storage is local.
In a multi server setup the storage is a SMB network share anyway, so the dox42 service is configured with the same UNC path as the front-ends. A single instance of the service is enough — it picks up the report jobs of all front-ends from the shared database.
2.8.1 Install
- Extract the shipped
Dox42Host v{version}.zippackage into the folder it should be installed to (for exampleC:\Program Files\iCLPortalDox42). - Double-click
install.bat— the script self-elevates (UAC prompt) if it's not already running elevated. It installs the Windows serviceiCLPortalDox42with--autostartand then launches the configuration wizard (config.bat) automatically. - When the configuration wizard appears, supply:
- Default SQL connection string — must point to the same database used by iCL Portal (shared Hangfire tables).
- Storage connection string — leave empty to use the local file system / file share, or paste an Azure Blob Storage connection string to use Azure Blob Storage.
- Service account —
NT AUTHORITY\NetworkService(default) or a domain/local account with SQL Server access. The wizard validates and resolves the account name. - Storage root folder (NodeRoot) — temp folder used to extract ICLR files; leave empty for the default
{install}\bin\app_data. - Application Insights iKey, customer tag, environment tag (e.g. Dev/Test/Prod). Provide the same values as in the web front-end to correlate logs and telemetry.
- Log folder — absolute path or
${basedir}/logsto resolve relative to the install folder.
- The wizard writes the values into
bin\iCL.Portal.Reporting.Dox42.Host.exe.configandbin\NLog.config, applies the service logon account viasc config, and offers to (re)start the service.
2.8.2 Change configuration later
Run config.bat from the install folder any time to re-configure the service. Existing values are shown in brackets and kept on ENTER without typing anything.
For deeper topics (storage modes, portal Settings > dox42 reference, troubleshooting) refer to the README.md that ships in the dox42 host package alongside the scripts.
3 Installing icl portal (multi server)
For a multi server scenario, you will have to create another virtual machine and follow the instructions from 2. Note, that you can add additional front-ends any time, as long as the load balancer supports this. Hint: When it comes to the web.config, you should be able to simply copy it from the first web front-end and use it on the second machine. There are several additional steps required: setting up the load balancer and setting up redis.
3.1 Setting up the load balancer
Any third party load balancer can be used in this scenario, therefore, the setup is out of scope of this manual. Note, however, that no special routing – like sticky routing – is required, as the iCL Portal web front-ends store their state in the distributed cache.
3.2 Setting up the distributed cache (Redis)
The distributed cache is the short-time memory of the web front-ends and, thus, must be within the same subnet and have a fast ethernet connection. Also, it is strongly recommended to run the redis cache on a separate machine. Note, that the makers of redis strongly recommended to run redis on Linux (such as Ubuntu). You can find detailed instructions here . However, Microsoft also maintains a windows port of Redis, which can be found here. As it is easier to setup, this documentation will show you how to run the windows version of redis.
3.2.1 Setting up Redis on Windows
First, download the latest release of Redis from https://github.com/MicrosoftArchive/redis/releases (every version from 3.0 is supported). At the time of this writing, this is version 3.0.504. Download the Redis-x64-x.x.xxx.msi package
Once ready, run the installer and follow the installation instructions. Basically, you can keep all the defaults. Redis will be installed to C:\program files\redisNext, configure a password in redis.windows.conf by opening it with notepad. Scroll down to the security section and uncomment the requirepass line:Chose a very long password (at least 100 characters) and do not keep the default (foobared)Finally, make sure that you configure an inbound firewall rule on port 6379
Note, that you can additionally strengthen the security of redis, by only allowing inbound connections from the IP addresses of the iCL Portal web front-ends!
3.2.2 Configuring iCL Portal to use Redis
To instruct iCL portal to actually use Redis, open the Web.config file (Note that you will have to do this on each web front-end)
Add the following key Abp.Redis.Cache to the <connectionStrings> node
<connectionStrings>
<!-- connection string for mssql -->
<add name="Default" connectionString="…" />
<!-- connection string for redis -->
<add name="Abp.Redis.Cache" connectionString="192.168.178.101:6379,password=foobared,abortConnect=False"/>
</connectionStrings>
Note, that you have to enter the IP address of the virtual machine, which is running Redis - 192.168.178.101 is just a demo value!
Also, make sure that you use the password, that you configured in the previous step instead of foobared
Add the following <sessionState> node to the beginning of the <system.web> node
<system.web>
<!-- command this out for using REDIS in a scale out scenario -->
<sessionState mode="Custom" customProvider="iCL.Portal.SessionState.Redis">
<providers>
<add name="iCL.Portal.SessionState.Redis" type="Microsoft.Web.Redis.RedisSessionStateProvider"
connectionString="Abp.Redis.Cache"
applicationName="iCL.Portal.Session" />
</providers>
</sessionState>
...
</system.web>
And finally, change the <modules> node in <system.webServer> to contain the following two highlighted elements:
<system.webServer>
<modules runAllManagedModulesForAllRequests="true">
<!-- .Net462+ requires us to switch to a new session state module (see https://github.com/Azure/aspnet-redis-providers/issues/104) -->
<remove name="Session" />
<add name="Session"
type="Microsoft.AspNet.SessionState.SessionStateModuleAsync, Microsoft.AspNet.SessionState.SessionStateModule, Version=1.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
preCondition="integratedMode" />
<remove name="ApplicationInsightsWebTracking"/>
<add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler"/>
</modules>
...
Once you are finished with the configuration, save the Web.config. That will cause iCL Portal to restart. To make sure that the connection to Redis works, open the latest error.log file of iCL Portal. (If you did not change the NLog.config file, then these should be in <webroot>\App_Data\Logs)
If iCL Portal takes a very long time to start up and the error.log is filled with messages like StackExchange.Redis.RedisConnectionException: No connection is available to service this operation, then you need to go over your redis configuration once more!
4 Configuring the Microsoft Distributed Transactions Coordinator Service
In case your error log or any request to iCL Portal shows this exception:
System.Data.Entity.Core.Entityexception: The Underlying Provider Failed On Open. ---> System.Transactions.Transactionmanagercommunicationexception: Network Access For Distributed Transaction Manager (Msdtc) Has Been Disabled. Please Enable Dtc For Network Access In The Security Configuration For Msdtc Using The Component Services Administrative Tool. ---> System.Runtime.Interopservices.Comexception: The Transaction Manager Has Disabled Its Support For Remote/Network Transactions. (Exception From Hresult: 0x8004d024)
To resolve this issue, you need to configure DTC access on all machines, that participate in coordinating distributed transactions. For iCL Portal, this is
- Every machine running the web application
- The database server
4.1.1 Solution part 1
- Enable network access.
- Open the server the web-frontend runs on (iCL Portal website)
- Open Server Manager => Tools => Component Services
- Alternatively, you can press the Windows button and search for
dcomcnfg - Expand Component Services => Computers => My Computer => Distributed Transaction Coordinator and then open its Properties view from the context menu
- In the Security tab, enable Network DTC Access
4.1.2 Solution part 2
Enable Firewall Exceptions for MS DTC
Where Windows Firewall is in use, you must add a firewall exception for the Microsoft Distributed Transaction Coordinator (MS DTC) at each computer that participates in coordinating distributed transactions. To configure this change, use Windows Firewall in Control Panel to enable a firewall exception at each computer in the network running DTCs that require network connectivity.
Membership in Administrators, or equivalent, is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups
- Open Windows Firewall. To open Windows Firewall, on the Start menu, click Control Panel. In Control Panel, do one of the following:
a. Under Security,
click Allow a program through Windows Firewall.b. If Control Panel is in Classic view, click Windows Firewall.
- On the Exceptions tab, select the Distributed Transaction Coordinator check box.
- Click OK.