Configuring Load Balancing for the Hyland IdP Server - Identity and Access Management Services - 3.0 - 3.0 - Other

This section describes the additional steps required to successfully create a load-balanced Hyland IdP server environment. These steps must be completed on each IdP server in the load-balanced environment. See the following assumptions and considerations:

Note: It is assumed that each server has been installed, initialized, and configured before starting this process, and can be confirmed to function as expected without load balancing.

The following considerations need to be accounted for before attempting to load balance the servers:

Each server in the load-balanced environment should use the same idpconfig.json file. If a single, shared file cannot be used, the idpconfig.json files must be exactly the same between servers. In a default installation, the idpconfig.json file is located on each server at C:\Program Files\Hyland\identityprovider.
The identity running the application pool for each Hyland IdP server must have Modify access to the ipdconfig.json file.
The same keyfile directory, used for encrypting and decrypting cookies, tokens, and other values, must be accessible to all Hyland IdP servers in the load-balanced environment.
The identity running the application pool for each Hyland IdP server must have Modify access to the keyfile location.
The settings configured in the appsettings.json file of each Hyland IdP server must match all other Hyland IdP servers in the environment. In a default installation, the appsettings.json file is located on each server at C:\Program Files\Hyland\identityprovider\config.

Note:
Unlike the idpconfig.json file, a single appsettings.json file cannot be moved to a common location for all Hyland IdP servers to use. It is a best practice to configure a single Hyland IdP server for load balancing, then overwrite the appsettings.json file on each other server with a copy of the same correctly configured appsettings.json file.
The same signing and encryption certificates need to be installed to the Personal Store under LocalMachine on each Hyland IdP server in the load-balanced environment. The identity running the application pool for each Hyland IdP server must have Read access to the private keys of the signing and encryption certificates.
As of 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.

To configure a Hyland IdP server for load balancing:

Open the appsettings.json file of the Hyland IdP server in a plain-text editor. In a default installation, this file is located at: C:\Program Files\Hyland\identityprovider\config

Update the following configuration items for load-balancing.

Item	Value and Description
KeyEncryptionCertificateThumbprint	The thumbprint of the RSA certificate being used for encryption, which can be found in the IIS bindings or in the Windows Certificate Store. The default value of null must be replaced with the actual thumbprint. The encryption certificate must include digital signatures key usage and be placed in the personal store of the local machine. The same certificate must be used for each Hyland IdP server in the load-balanced environment. Note: The identity running the Hyland IdP server application pool must have Read access to the private key of the encryption certificate. For details on configuring certificate permissions, see the documentation provided by Microsoft for the Certificate Manager tool.
KeyFilePersistenceLocation	The fully qualified UNC path of the common directory where the keyfile used for encrypting and decrypting cookies, tokens, and other values is stored. Each server in the load-balanced environment must use the same keyfile location. By default, the ASP.NET\DataProtection-Keys directory within the local application data directory is used, but that location is not accessible by other servers. Note: The identity running the Hyland IdP server application pool must have Modify access to the keyfile location in order to create and store keyfiles. Make sure you include a double-slash (\\) between directories in the path to account for JSON formatting. For example, \\\\my.server\\my\\path
IdPConfigFilePath	The fully qualified UNC share path of the idpconfig.json file. Each server in the load-balanced environment should use the same idpconfig.json file. If a single, shared file cannot be used, the idpconfig.json files must be exactly the same between servers. The default value is idpconfig.json and can only be accessed by that server. Make sure you include a double-slash (\\) between directories in the path to account for JSON formatting. For example, \\\\my.server\\my\\path\\idpconfig.json Note: The identity running the Hyland IdP server application pool must have Modify access to the idpconfig.json file.

Item

Value and Description

KeyEncryptionCertificateThumbprint

The thumbprint of the RSA certificate being used for encryption, which can be found in the IIS bindings or in the Windows Certificate Store. The default value of null must be replaced with the actual thumbprint.

The encryption certificate must include digital signatures key usage and be placed in the personal store of the local machine. The same certificate must be used for each Hyland IdP server in the load-balanced environment.

Note:

The identity running the Hyland IdP server application pool must have Read access to the private key of the encryption certificate. For details on configuring certificate permissions, see the documentation provided by Microsoft for the Certificate Manager tool.

KeyFilePersistenceLocation

The fully qualified UNC path of the common directory where the keyfile used for encrypting and decrypting cookies, tokens, and other values is stored. Each server in the load-balanced environment must use the same keyfile location. By default, the ASP.NET\DataProtection-Keys directory within the local application data directory is used, but that location is not accessible by other servers.

Note:

The identity running the Hyland IdP server application pool must have Modify access to the keyfile location in order to create and store keyfiles.

Make sure you include a double-slash (\\) between directories in the path to account for JSON formatting. For example, \\\\my.server\\my\\path

IdPConfigFilePath

The fully qualified UNC share path of the idpconfig.json file. Each server in the load-balanced environment should use the same idpconfig.json file. If a single, shared file cannot be used, the idpconfig.json files must be exactly the same between servers.

The default value is idpconfig.json and can only be accessed by that server. Make sure you include a double-slash (\\) between directories in the path to account for JSON formatting. For example, \\\\my.server\\my\\path\\idpconfig.json

Note:

The identity running the Hyland IdP server application pool must have Modify access to the idpconfig.json file.

Save and close the appsettings.json file.
Recycle the application pool of the Hyland IdP server for the changes to take effect.
Update each appsetting.json file on each Hyland IdP server in the load-balanced environment to match, so that each server has the exact same values for the required settings.