Platform Configuration Tool

Important: The Platform Configuration Tool works for upgrades from a version released in the past three years relative to the current major version. Post-installation checks and operations work after installing Orchestrator.

Overview

The UiPath Platform Configuration Tool is a PowerShell script used to assist you in the successful installation/upgrade of Orchestrator. It helps you check the sanity and readiness of your environment before an upgrade, and assists you in performing several operations post-installation.

The tool is available for download below and is also bundled with the UiPathOrchestrator.msi installer. The bundled script can be found in the Tools folder of the Orchestrator installation directory, C:\Program Files (x86)\UiPath\Orchestrator\ by default. The script checks the Orchestrator machine. In the case of a multi-node installation, it is enough to run the tool on one node.

The Platform Configuration Tool does not follow the same versioning scheme as the UiPathOrchestrator.msi installer and can be updated outside of the product release cycle. We recommend that you always download and use the latest version of the tool which is available below.

Download the tool

Prerequisites

Software	Compatible Version
PowerShell	5.1
WebAdministration Module	N/A
pki Module	N/A

Script Cmdlets

The script consists of three cmdlets intended to perform specific functions. A cmdlet-invoking command and its relevant parameters can be entered in the command line for immediate execution.

Cmdlet	Description
Test-PlatformReadiness	Invoked using the -Readiness command. Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation.
Update-UiPathUrl	Invoked using the UpdateUiPathUrl command. Updates the public address of Orchestrator and checks if the new address is valid with the current certificate.
Update-UiPathCertificate	Invoked using the UpdateUiPathCertificate command. Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate.
AddHostAdmin	Invoked using the AddHostAdmin command. Adds a system administrator to the host tenant.

Pre-Installation Checks

Asp.Net Core

Checks if ASP.NET Core IIS module v3.1.x+ is installed and functional. If it's not, you are prompted to uninstall and reinstall the ASP.Net Core Hosting Bundle.

CyberArk AIM

Checks if the CyberArk AIM agent is installed under the C:\Program Files (x86)\CyberArk folder. If it's not, the user is prompted to add CLIPasswordSdk.exe in the UiPath.Orchestrator.dll.config file using Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath key after the installation.

This check is not performed if CyberArk is not found in UiPath.Orchestrator.dll.config.

Web.config Encryption

Checks if the web.config file is decrypted. If encrypted, you need to manually decrypt it before upgrading. After the upgrade, most of Orchestrator's configuration settings are moved to UiPath.Orchestrator.dll.config.

Learn how to encrypt the UiPath.Orchestrator.dll.config file.

Web.config Locked Sections

Checks if the <system.webServer> element contains any locked sections. If such sections exist, you need to manually unlock them in IIS.

SQL Server Scaleout

Checks if SQL Server Scaleout is used. You are informed that during the installation Redis Scaleout is enabled.

Credential Store Plugins

Checks that external credential store plugins target a supported framework.

NLog Plugins

Checks that NLog plugins target a supported framework.

FileSystem Buckets

This check validates that the Buckets.FileSystem.Allowlist app setting is present in Orchestrator versions starting with v2020.4. This covers both pre-installation checks (Orchestrator v2020.4) and post-installation checks (Orchestrator v2020.10). Orchestrator versions prior to v2020.4 skip this check.

• To perform the following checks, you need to decrypt the connectionStrings and appSettings config sections. If any of these configuration sections is encrypted, then a warning prompts you in the terminal, and the rest of the buckets validations are skipped.

  Could not determine if any buckets with file system provider are in use. Config section 'connectionString' is encrypted, could not find the sql connection string to the UiPath database.

• If, for any reason, the buckets could not be retrieved from the database, a warning prompts you in the terminal, and the rest of the validations are skipped as well.

  Could not determine if any buckets with file system provider are in use. Could not connect to the UiPath Database.

• This validation is performed on the retrieved buckets root paths from the Orchestrator database buckets table. If there are any unqualified paths, then a warning prompts you in the terminal. A similar check for the unqualified paths is done for the paths in the Buckets.FileSystem.Allowlist app setting in the config file.
• If any of the paths in the two sources is not valid or is unqualified, then it is not be taken into considerations for the rest of the validations described below.
• If the Buckets.FileSystem.Allowlist app setting is not set in the config file, then the terminal prompts you with an error asking you to add the allowlist to the config file. The suggested paths are the root path of the buckets that use the file system provider.

  All storage buckets using the file system provider are not on the allowed list. Add the following setting in the configuration file to allow all exiting buckets root paths: <add key="Buckets.FileSystem.Allowlist" value="C:\work\stuff\Bucket\|C:\work\stuff\Bucket1\" />

• If the Buckets.FileSystem.Allowlist app setting is set in the config file, then a validation is performed on the buckets root path that use the FileSystem provider. If a bucket root path is not a subpath of any of the paths defined in the allowlist, then a warning prompts you in the terminal asking you to add the bucket root path to Buckets.FileSystem.Allowlist .

  There are some storage buckets using the file system provider that are not on the allowed list. The buckets feature will not work for buckets with root paths that are not on the allowed list. Check if any of the following paths are required to be on the allowed list and add them to the 'Buckets.FileSystem.Allowlist' key in configuration file: |C:\work\stuff\Buckets\|C:\work\stuff\Bucket1\

• Otherwise, if every bucket root path is a subpath of any path in the allowed list, then the terminal displays a success message.

  All storage buckets using file system provider have the root path on the allow list in the configuration file.

Post-Installation Checks

Certificate Requirements

Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.

SSL Certificate Checks

• the hostname of the Orchestrator site matches the Subject or a Subject Alternate Name (including wildcards) on the certificate,
• has a valid trust chain, and
• is not expired.

Identity Server Token-Signing Certificate Checks

• The certificate has the appropriate key size (2048 bits or larger),
• has a private key accessible by the AppPool user, and
• is not expired.

Other Considerations

Check the docs on installation considerations for other areas impacted by an upgrade to 2020.10+ that you need to be aware of.

Running the Script

Command Reference

Command & Parameters	Description
-Readiness	Checks the sanity and readiness of your environment before an upgrade and the certificate requirements after the installation. Parameters: -SiteName -Help -InstallationDirectory
-UpdateUiPathUrl	Updates the public address of Orchestrator. Parameters: -SiteName -OrchestratorUrl -SqlConnectionString Important: The SQL Server PowerShell module is required to use this command. The module is installed by default with SQL Server. If you’re working on a machine that doesn’t have the module installed, see here how to install it. Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
-UpdateUiPathCertificate	Updates the Orchestrator SSL certificate or the Identity Server token-signing certificate. Use it in conjunction with the -readiness command to check the validity of the new certificates. Parameters: -SiteName -NewTokenSigningThumbprint -NewSSLThumbprint -KeepOldCertificate
-AddHostAdmin	If access to the host organization is lost (for example, if the password for the system administrator is lost or the only users with system administrator accounts leave the company), you can use this command to add or restore a system administrator. Parameters: -SiteName -HostAdminUsername -HostAdminPassword -HostAdminEmail

Script Parameters

Parameter	Description
-SiteName	Optional. The name of the Orchestrator website on the target machine. Defaults to "UiPath Orchestrator". -InstallationDirectory and SiteName are mutually exclusive.
-Help	Optional. Displays information about the tool options or available commands, such as the commands' syntax or the checks it performs.
-InstallationDirectory	Optional. The path of Orchestrator's installation directory. Usually C:\Program Files (x86)\UiPath\Orchestrator\. -InstallationDirectory and SiteName are mutually exclusive. Note: Make sure the installation directory path ends with a trailing backslash (\).
-OrchestratorUrl	Mandatory. The new public address of Orchestrator.
-SqlConnectionString	Optional. UiPath database connection string. If left empty, the value is read from the appsettings.Production.json file.
-NewTokenSigningThumbprint	Optional. The thumbprint of the new token signing certificate used by the Orchestrator Identity Server.
-NewSSLThumbprint	Optional.The thumbprint of the new SSL certificate used by the Orchestrator Web App.
-HostAdminUsername	Only mandatory when using the -AddHostAdmin command. Username of the host admin user to create or restore.
-HostAdminPassword	Email of the host admin user to create or restore when using the -AddHostAdmin command. Only mandatory if using these external identity providers: Google Azure Active Directory SAML with email user mapping strategy
-HostAdminEmail	Password of the host admin user to create when using the -AddHostAdmin command. Password is only mandatory if the user is a basic authentication user. The password will need to be changed on first login.

Examples

To work with the Platform Configuration Tool script, open an Administrator PowerShell script.

Locate the directory where you unzipped the Platform Configuration Tool archive and change the directory to that location:

cd "C:\Program Files (x86)\UiPath\Orchestrator\Tools\PlatformConfiguration"

Performing a Readiness Check

The following example enables you to perform a validation of the pre-installation requirements of Orchestrator. The procedure logs its steps and output extra information at the -verbose level.

.\Platform.Configuration.Tool.ps1 ` 
-Readiness ` 
-SiteName "UiPath Orchestrator"

Pre-Installation checks successful output (for upgrades from 2020.4).

Validating 22.10 pre-installation requirements... Checking AspNetCore hosting module... AspNetCore hosting module is installed. Checking CyberArk CLIPasswordSDK.exe path... CyberArk CLIPasswordSDK.exe was found at the default installation path 'C:\Program Files (x86)\CyberArk\ApplicationPasswordSdk\CLIPasswordSDK.exe'. Checking Web.config sections encryption... Web.config sections are not encrypted. Checking IIS configuration locked sections... Configuration sections are not locked. Checking Orchestrator ssl certificate subject alternative names... Orchestrator host name is valid for the ssl certificate subject alternative names. Checking sql server scaleout use... Sql server scaleout is not used. Checking external credential store plugins target framework... Credential stores plugins validation is finished. Checking external NLog plugins target framework... NLog plugins validation is finished. Checking buckets with file system storage provider... All storage buckets using file system provider have the root path on the allowed list in the configuration file. Checking platform certificates... Platform certificates validation is finished. All 22.10 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).

Changing Certificates After Installation

The following example enables you to update the Orchestrator SSL and the Identity Server token-signing certificates.

.\Platform.Configuration.Tool.ps1 ` 
-UpdateUiPathCertificate ` 
-KeepOldCertificate $false `
-SiteName "UiPath Orchestrator" ` 
-NewSSLThumbprint "a1b2c3d4" ` 
-NewTokenSigningThumbprint "z6y5x4v3"

Note:

• Any appsettings files should be decrypted prior to using the script.
• Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.
• The KeepOldCertificate parameter indicates if the current certificate should continue to be used as a validation key for tokens that were signed with it.

If the private key has not been added to the certificate, you can add it manually by taking the following steps:

1. To locate the private key, start Internet Information Service (IIS) Manager, and select Application Pool. You should find the private key for each service under the Identity column.
2. Go to Manage Computer Certificates under Control Panel.
3. Go to Personal/Certificates.
4. Right-click New certificate, then go to All Tasks > Manage PrivateKey to add the private key.

Note: If you have multiple Orchestrator nodes, please make sure to update the certificate on all server nodes.

Changing Orchestrator URL

The following example enables you to update the Orchestrator URL.

.\Platform.Configuration.Tool.ps1 ` 
-UpdateUiPathUrl ` 
-OrchestratorUrl "https://mydomainname" ` 
-SiteName "UiPath Orchestrator" ` 
-SqlConnectionString "Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"

Note: Although we recommend using lowercase for the Orchestrator URL, the tool automatically converts any uppercase string to lowercase.

Creating a New System Administrator

The following example creates a new system administrator on the host tenant using basic authentication. Note that if an external identity provider is set as exclusive, basic authentication is only accessible through the hostlogin URL documented in Accessing Identity Management Portal .

.\Platform.Configuration.Tool.ps1 ` 
-AddHostAdmin ` 
-SiteName "UiPath Orchestrator" ` 
-HostAdminUsername someuser ` 
-HostAdminPassword som3pwd! ` 
-HostAdminEmail [e-mail]

Output

The output is color-coded.

Color	Description
Red	Blockers Elements are missing or are not configured and will prevent the installation.
Yellow	Warnings You can install Orchestrator, but additional benefits will be absent.
Green	Messages The environment is ready for installation.