orchestrator

2023.4

false

Orchestrator Installation Guide

DELIVERY:

Automation Cloud Automation Cloud Public Sector Automation Suite Standalone

Last updated Oct 3, 2024

Identity Server Troubleshooting

Viewing Additional Information in Logs

There may be situations when Identity Server throws error messages containing sensitive information. For example, if the certificate used to sign the access tokens generated by the Identity Server is a public key on 1024 bits, instead of 2048 bits, you'll receive the following error message when trying to login to a freshly installed or upgraded Orchestrator tenant:

InternalServerError - IDX10630 The '[PII is hidden. For more details, see https://aka.ms/IdentityModel/PII.]'

To enable the logging of sensitive information such as certificate public keys or hidden PII (personally identifiable information), update the following setting in the Identity Server's appsettings.Production.json file, within your existing AppSettings section:

"AppSettings": {
    "EnablePII": true
  },"AppSettings": {
    "EnablePII": true
  },

Note: Even after updating the EnablePII setting in the Identity Server's appsettings.Production.json file, some information might still be hidden. To display Orchestrator PII, add the ExternalAuth.ShowPII setting to Orchestrator's UiPath.Orchestrator.dll.config.

With this new setting, the error message reveals more useful information:

The 'Microsoft.IdentityModel.Tokens.X509SecurityKey, KeyId: 'F9B1F6C18B728C02C8853470C71C365F000C86B5', InternalId: 'd3dadcac-e5aa-48e6-a20a-9232a3c3d16f'.' for signing cannot be smaller than '2048' bits. KeySize: '1024'. (Parameter 'key.KeySize')

Faulty .NET Core Hosting Bundle Installation

There may be situations when .NET Core Hosting Bundle is not installed properly. This may have the following effects:

.NET Core applications running in IIS (such as identity Server) do not start. Instead, the System.IO.IOException: IDX20807: Unable to retrieve document error is displayed.
An error appears when you access Handler Mappings for Identity Server in IIS.
The 500.19 Error Code: 0x8007000d error occurs when visiting the https://localhost/identity URL in a browser.

The obvious solution for this issue is to reinstall the .NET Core Hosting Bundle.

Unable to Access External Providers Page After Upgrading to Orchestrator 2020.4+

When you update your Orchestrator to 2020.4+, Identity Server migrates your previous settings. If you had previously enabled Windows authentication while having set up automatic login for Windows AD users, then after performing the upgrade, the users can't access the External Providers page if they previously logged into Identity Server. The users are logged in to the tenants directly after entering their Windows credentials.

Without being able to access the Login page, the host admin can't log in to the Host tenant, and they can't access Identity Management Portal.

If this is your case, open a new browser in incognito mode and type https://<OrchestratorURL>/identity/configuration.

/api/account/authenticate Calls Failing For Users Who Changed Passwords at First Login

For newly created users who change their password when they first log in to Orchestrator, any calls performed via PowerShell to the /api/account/authenticate endpoint result in an Invalid credentials, failed to login error message.

Users in this situation should change their password from Orchestrator's Profile page.

Keyset Does Not Exist Error After Installation

After installing UiPath Orchestrator 2020.4, the Keyset does not exist Internal Server Error might occur if the certificate used for Identity Server does not have the appropriate permissions set.

Run the following PowerShell script as Admin to grant permissions for the certificate:

import-module WebAdministration
$siteName = 'UiPath Orchestrator'
$binding = (Get-ChildItem -Path IIS:\SSLBindings | Where Sites -eq $siteName)[0]
$certLoc = "cert:\LocalMachine\MY\$($binding.Thumbprint)"
$cert = Get-Item $certLoc
$keyPath = $env:ProgramData + "\Microsoft\Crypto\RSA\MachineKeys\"
$keyName = $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName
$keyFullPath = $keyPath + $keyName
$acl = (Get-Item $keyFullPath).GetAccessControl('Access')
$permission="IIS_IUSRS","Full","Allow"
$accessRule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $permission
$acl.AddAccessRule($accessRule)
Set-Acl -Path $keyFullPath -AclObject $aclimport-module WebAdministration
$siteName = 'UiPath Orchestrator'
$binding = (Get-ChildItem -Path IIS:\SSLBindings | Where Sites -eq $siteName)[0]
$certLoc = "cert:\LocalMachine\MY\$($binding.Thumbprint)"
$cert = Get-Item $certLoc
$keyPath = $env:ProgramData + "\Microsoft\Crypto\RSA\MachineKeys\"
$keyName = $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName
$keyFullPath = $keyPath + $keyName
$acl = (Get-Item $keyFullPath).GetAccessControl('Access')
$permission="IIS_IUSRS","Full","Allow"
$accessRule = New-Object -TypeName System.Security.AccessControl.FileSystemAccessRule -ArgumentList $permission
$acl.AddAccessRule($accessRule)
Set-Acl -Path $keyFullPath -AclObject $acl

Note:

Modify the $siteName value according to your Orchestrator installation.

Restart the IIS site after performing any configuration changes.

RobotKeyMigration Fails During Update

The Orchestrator service should be stopped prior to any update / upgrade of the Identity Server service. Changes made to robots in Orchestrator during the Identity Server update result in a failed update.

If this occurs, stop the Orchestrator service and re-run the migration.

Deployments Using Languages That Contain Non-ascii Characters

Multiple issues have been linked to localization issues in languages containing non-ascii characters. For full localization support, please upgrade to the 20.10+ Insights release.

Configuring SAML Settings Unavailable in Identity Server UI

The following workaround addresses scenarios where you installed Orchestrator v2020.4 or later and need specific settings for your SAML provider to work.

Whereas the Identity Server UI should meet most of your needs in terms of SAML configuration, this section provides a way to control additional SAML settings that are not exposed by default. For a complete list of available settings, refer to the official Sustainsys.Saml2 documentation.

Sustainsys.Saml2 is the library Identity Server relies on for SAML support, and it uses an XML configuration file. To get access to the fields that are unavailable in the Identity Server UI, you need to override this XML file. The following procedure describes how you can manage that:

Make sure you enabled and properly configured the SAML external identity provider on the External Providers page in Identity Management Portal.
Edit the appsettings.json or appsettings.Production.json file to include the following section at the root level. This tells Identity Server to look for a file called saml2.xml in the same folder as the web application and the appsettings.json or appsettings.Production.json.
```
"Authentication": {
   "Saml2": {
     "ConfigFile": "saml2.xml"
   }
 },"Authentication": {
   "Saml2": {
     "ConfigFile": "saml2.xml"
   }
 },
```
Create an XML file called saml2.xml and add the SAML configuration.

Map the fields on the External Providers page in Identity Management Portal to the corresponding nodes in saml2.xml.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="sustainsys.saml2" type="Sustainsys.Saml2.Configuration.SustainsysSaml2Section, Sustainsys.Saml2" />
 </configSections>
  <sustainsys.saml2 
      entityId="--1--"
      returnUrl="--5--">
    <identityProviders>
      <add 
          entityId="--2--" 
          signOnUrl="--3--" 
          allowUnsolicitedAuthnResponse="--4--" 
          binding="--6--">
        <signingCertificate 
            storeName="--7--" 
            storeLocation="--8--"
            findValue="--9--" 
            x509FindType="FindByThumbprint"/>
      </add>
    </identityProviders>
    <serviceCertificates>
      <add
          use="Both"
          storeName="--10--" 
          storeLocation="--11--"
          findValue="--12--" 
          x509FindType="FindByThumbprint"/>
    </serviceCertificates>
  </sustainsys.saml2>
</configuration><?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="sustainsys.saml2" type="Sustainsys.Saml2.Configuration.SustainsysSaml2Section, Sustainsys.Saml2" />
 </configSections>
  <sustainsys.saml2 
      entityId="--1--"
      returnUrl="--5--">
    <identityProviders>
      <add 
          entityId="--2--" 
          signOnUrl="--3--" 
          allowUnsolicitedAuthnResponse="--4--" 
          binding="--6--">
        <signingCertificate 
            storeName="--7--" 
            storeLocation="--8--"
            findValue="--9--" 
            x509FindType="FindByThumbprint"/>
      </add>
    </identityProviders>
    <serviceCertificates>
      <add
          use="Both"
          storeName="--10--" 
          storeLocation="--11--"
          findValue="--12--" 
          x509FindType="FindByThumbprint"/>
    </serviceCertificates>
  </sustainsys.saml2>
</configuration>

Add the settings you need. For example, use publicOrigin in load-balanced scenarios or minIncomingSigningAlgorithm if you want to change the default SHA256 option.
Save the files and restart the Identity Server web application in IIS. If you encounter any errors with the SAML configuration, error events should be visible in your logs. You can use Windows Event Viewer, the default tool for this purpose.

Updating the Bearer Token Expiration

Orchestrator's UiPath.Orchestrator.dll.config file does not offer a way to update the bearer token expiration time.

Changes are possible only by adjusting the AccessTokenLifetime property of the Orchestrator.Ropc client in the Identity Server’s Clients database.

In the following example, the bearer token expiration time is set to 86400 seconds (24 hours).

UPDATE [identity].[Clients]
SET AccessTokenLifetime = 86400
WHERE ClientName = 'Orchestrator.Ropc'UPDATE [identity].[Clients]
SET AccessTokenLifetime = 86400
WHERE ClientName = 'Orchestrator.Ropc'

Setting a Timeout Interval for the Management Portals

Orchestrator's UiPath.Orchestrator.dll.config file does not offer a way to update the expiration time for the token used to authenticate to the host- and organization-level Management portals. Therefore, user sessions do not time out.

To set a time interval for timeout for these portals, you can update the accessTokenLifetime property by following the below instructions:

A. Via API

Obtain a client installation token for the host.
Log out the system administrator user.
Navigate to the Identity Server Swagger API at https://<server>/identity/swagger.
Authorize using Bearer <token>, where the <token> value is the one obtained at step 1.
Retrieve client details using GET /api/Client/6654E78D-8490-4ABE-9C40-D28267C89F3A.
Copy the response body and change the accessTokenLifetime property value to the desired token expiration value (in seconds).
Use the edited response body in a PUT /api/Client/6654E78D-8490-4ABE-9C40-D28267C89F3A request.
Verify that the response body contains the updated value for the accessTokenLifetime property.

Via SQL

The below example sets the timeout interval to 86400 seconds (24 hours):

UPDATE [identity].[Clients] SET AccessTokenLifetime = 86400 WHERE ClientName = 'Portal.OpenId'UPDATE [identity].[Clients] SET AccessTokenLifetime = 86400 WHERE ClientName = 'Portal.OpenId'

Intermittent 404 Error When Logging Out

The request to log out can sometimes have a URL query string that exceeds the default maximum query string length allowed by IIS. Here are two ways to modify this setting:

Important: Changes to the web.config are not preserved on upgrade as of the 2021.10 release.

Using the IIS Manager Tool

In the Connections tree, navigate to Sites -> UiPath Orchestrator -> Identity.
Double-click the Request Filtering icon.
On the right-side pane, click Edit Feature Settings.
Increase the value for Maximum query string (Bytes).

Note: You may also want to increase the Maximum URL length (Bytes) since the query string is part of the overall URL length.

Modifying Identity Web.config

Find the web.config file for Identity.
- By default, this is C:\Program Files (x86)\UiPath\Orchestrator\Identity\web.config for MSI installations.
- For Azure App Service installations, open the App Service Editor under Development Tools and navigate to wwwroot/Web/web.config. Make sure you are modifying Identity, and not Orchestrator.

Open with a text editor and find the requestFiltering node, which is under the security node. Under requestFiltering, add a requestLimits node as shown below:

<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <security>
        <requestFiltering>
          <requestLimits maxQueryString="4096" />
        </requestFiltering>
      </security>
    </system.webServer>
  </location>
</configuration><configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <security>
        <requestFiltering>
          <requestLimits maxQueryString="4096" />
        </requestFiltering>
      </security>
    </system.webServer>
  </location>
</configuration>

Upgrade Fails With Timeout

Upgrades to 2022.4 may fail with a timeout error due to an Identity Server database issue. To fix the problem, you must run the following script and retry the operation.

Important: Running the following script invalidates all tokens, and requires all applications and robots to reauthenticate.

DELETE [identity].[PersistedGrants] WHERE [Expiration] < GETUTCDATE()
DECLARE @ConsumedTime DATETIME = DATEADD(SECOND, -7200, GETUTCDATE())
DELETE [identity].[PersistedGrants] WHERE [ConsumedTime] IS NOT NULL AND [ConsumedTime] < @ConsumedTimeDELETE [identity].[PersistedGrants] WHERE [Expiration] < GETUTCDATE()
DECLARE @ConsumedTime DATETIME = DATEADD(SECOND, -7200, GETUTCDATE())
DELETE [identity].[PersistedGrants] WHERE [ConsumedTime] IS NOT NULL AND [ConsumedTime] < @ConsumedTime

404 when user in multiple tenants attempts authentication

Users who are part of multiple tenants encounter a "Error while contacting partition service to validate the organization (#404)" error during authentication. This error occurs because the request to authenticate exceeds the default query string length limit in IIS (2048 characters), especially for users are associated with a significant number of tenants (typically more than 30 tenants).

To address this issue, you can adjust the query string length limit in IIS.

Using the IIS Manager Tool

In the Connections tree, navigate to Sites -> UiPath Orchestrator -> Identity.
Double-click the Request Filtering icon.
On the right-side pane, click Edit Feature Settings.
Increase the value for Maximum query string (Bytes).

Note: You may also want to increase the Maximum URL length (Bytes) since the query string is part of the overall URL length.

Modifying Identity Web.config

Find the web.config file for Identity.
- By default, this is C:\Program Files (x86)\UiPath\Orchestrator\Identity\web.config for MSI installations.
- For Azure App Service installations, open the App Service Editor under Development Tools and navigate to wwwroot/Web/web.config. Make sure you are modifying Identity, and not Orchestrator.

Open with a text editor and find the requestFiltering node, which is under the security node. Under requestFiltering, add a requestLimits node as shown below:

<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <security>
        <requestFiltering>
          <requestLimits maxQueryString="4096" />
        </requestFiltering>
      </security>
    </system.webServer>
  </location>
</configuration><configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <security>
        <requestFiltering>
          <requestLimits maxQueryString="4096" />
        </requestFiltering>
      </security>
    </system.webServer>
  </location>
</configuration>