Upgrade Considerations - Identity and Access Management Services - 4.1 - 4.1 - Public - Other - external

Identity and Access Management Services

Platform
Other
Product
Identity and Access Management Services
Release
4.1
License

The following upgrade considerations apply when upgrading to newer versions of Hyland IAM Services, starting with the Hyland IdP server version specified.

General considerations

The following considerations apply generally when upgrading IAM Services.

  • Before upgrading, it is considered a best practice to create a backup copy of the Hyland IdP server configuration file (idpconfig.json). In a default installation, the Hyland IdP configuration file is located at C:\Program Files\Hyland\identityprovider.

    This file contains information on the tenants, providers, and clients configured for use with the Hyland IdP server. The backup copy can be referred to after the upgrade to help reconfigure the same tenants, providers, and clients in the upgraded system.

  • Upgrade procedures have changed starting in Hyland IdP 3.1.0. See the Hyland IdP 3.1.0 upgrade consideration for more information.

Hyland IdP 3.1.0
The functionality of the Hyland IdP installer has changed starting in Hyland IdP 3.1.0. When upgrading from an existing installation, the installer now detects the existing installation and can retain the previously configured idpconfig.json and appsettings.json configuration files. See the following considerations:
  • When choosing to retain the previously configured idpconfig.json and appsettings.json configuration files from Hyland IdP versions prior to 3.1.0, you must use the same installation directory where the previous version was installed.
  • For procedures on upgrading your existing Hyland IdP server, see Upgrading the Hyland IdP Server.
Hyland IdP 3.0.1
In load-balanced environments using SSL termination or when the Hyland IdP server is deployed behind a proxy server, you must properly configure the X-Forwarded-Host and X-Forwarded-Proto headers in the proxy server or load balancer, depending on your environment. For more information on configuring these headers, consult the Microsoft documentation
Hyland IdP 3.0.0
See the following considerations:
Hyland IdP 2.11.0

When upgrading to versions of Hyland IdP 2.11.0 or above, you must run the DatabaseMigration command to ensure compatibility for the database associated with your Hyland IdP configuration. To correctly run the DatabaseMigration command, see Migrating the IdP Server Database.

Hyland IdP 2.11.0

It is considered a best practice to create a backup copy of the Hyland IdP server application settings configuration file (appsettings.json) before upgrading to a newer version. However, if you are replacing the appsettings.json file with a backup copy from a previous version, some backwards compatibility settings may not be available in the earlier version of the appsettings.json file.

The following table lists backwards compatibility settings that are available in the Features block of the appsettings.json file for Hyland IdP 2.11.0. If you need any of these settings, they can be copied into the Features block of your appsettings.json file from the Features block of the default appsettings.json file included with your upgraded server.

Setting

Description

AdminAPI

The default value is false. Set this option to true to enable configuration of the Hyland IdP server using the Hyland IdP Administration client.

UseDeprecatedPasswordApi

The default value is false . Set this option to true to use the older, deprecated validation protocol instead of the newer validation protocol.

See Hyland IdP 2.2.0 for more information on this setting.

UseNewSamlModulePath

The default value is false. Set this option to true when using multiple external SAML providers.

AllowWildcardedCorsOrigins

The default value is false. Set this option to true to allow cross-domain origins to use wildcards.

EnableProviderConfigurationValidation

The default value is true. Provider configuration is checked before a new provider is added or any modification to an existing one is saved.

Hyland IdP 2.10.1

The configuration of the Allowed Cors Origin setting is no longer required when the list of cross-domain origins is already configured under the Redirect URLs and Post Logout Redirect URLs settings in Hyland IdP 2.10.0. If other origins exist that are not defined in either the Redirect URLs or Post Logout URLs options, then these must be configured in the Allowed Cors Origin setting.

Hyland IdP 2.6.0

The behavior of configuring the Allowed Cors Origin setting changed starting in Hyland IdP 2.6.0. A wildcard cannot be configured for the Allowed Cors Origin setting starting in Hyland IdP 2.6.0. If this setting contains a wildcard, the Hyland IdP returns the error Invalid client configuration for client X: AllowsCorsOrigin contains invalid origin: *. This value can also be left empty if specific origin values are not required.

Hyland IdP 2.2.0

The password validation protocol used by Hyland SCIM 2.1.1 was updated for use starting with Hyland IdP 2.2.0. If you are unable to upgrade to Hyland SCIM 2.1.1, you must configure an additional setting to allow the legacy protocol to still be used with the Hyland IdP server version 2.2.0 or newer. This setting is in the appsettings.json file of the Hyland IdP server, in the Features block: Change the value of the UseDeprecatedPasswordApi setting to true. By default, the value is set to false and the newer validation protocol is used.

"UseDeprecatedPasswordApi": true,
Hyland IdP 1.2.1

In December 2019 Microsoft ended support for Microsoft .NET Core 2.2 and the requirement for IAM Services was targeted to the supported Microsoft .NET Core 2.1 instead. Because of this, issues may occur with Microsoft .NET Core after upgrading the IAM Services components from the following versions:

  • Hyland IdP 1.0.0 and 1.2.0

  • Hyland SCIM server 1.0.0 and 1.1.0

  • Hyland IAM Configuration Application 1.0.0 and 1.1.0

To correctly set Microsoft .NET Core for IAM Services after upgrading, you must run the Repair operation for each component using either the installer or through the Add/Remove Programs functionality in Windows.