orchestrator
2023.4
false
- Getting Started
- Requirements
- Best Practices
- Installation
- Updating
- Identity Server
- Troubleshooting startup errors
Orchestrator Installation Guide
Last updated Oct 3, 2024
Identity Server AppSettings.json
The
appsettings.json file (C:\Program Files (x86)\UiPath\Orchestrator\Identity) contains the out-of-the-box configuration settings for Identity Server. A second, identical file, appsettings.Production.json, is the one that contains your specific Identity Server settings.
Important:
-
To configure Identity Server to your liking, you should modify the
appsettings.Production.jsonfile. This file overrides any pre-existent settings withinappsettings.jsonafter each installation process. -
If you use versions 2023.4 and up, and have modified
applicationhost.configby addingX-Content-Type-Options, you must remove it from the Identityappsettings.Production.jsonfile. See the following example:<?xml version="1.0" encoding="utf-8"?> <configuration> <location path="." inheritInChildApplications="false"> <system.webServer> <httpProtocol> <customHeaders> <remove name="X-Powered-By" /> <!-- <add name="X-Content-Type-Options" value="nosniff" /> --> </customHeaders><?xml version="1.0" encoding="utf-8"?> <configuration> <location path="." inheritInChildApplications="false"> <system.webServer> <httpProtocol> <customHeaders> <remove name="X-Powered-By" /> <!-- <add name="X-Content-Type-Options" value="nosniff" /> --> </customHeaders>
Note:
It is recommended that only administrators change the values of these parameters.
Additionally, it is recommended that you shut down the IIS server in order to modify
appsettings.Production.json settings under any circumstances.
Parameters that are not documented in this page should not be changed.
All parameters are case sensitive.
Settings can be configured in multiple places. Here are the priorities used by Identity Server when determining the value of a setting, listed from high (1) to low (3):
- Value within the
appsettings.Production.jsonfile - Value within the
appsettings.jsonfile - Default value set in the code. Used only if a specific setting can't be found within
appsettings.Production.jsonorappsettings.json.
The
appsettings.json file has an internal structure composed of multiple JSON sections separated by a comma.
The
ConnectionStrings section is used to store the Identity Server database connection string. This value is populated by the installer.
This setting has values within
appsettings.Production.json and appsettings.json.
"ConnectionStrings": { "DefaultConnection": "Server=.\\sqlexpress;Database=IdentityServer;User ID=<username>;Password=<password>;" }"ConnectionStrings": { "DefaultConnection": "Server=.\\sqlexpress;Database=IdentityServer;User ID=<username>;Password=<password>;" }The
EncryptionSettings section is used to store tenant encryption keys. The values are automatically migrated from Orchestrator's UiPath.Orchestrator.dll.config during installation.
This setting has values within
appsettings.Production.json and appsettings.json.
"EncryptionSettings": {
"EncryptionKey": "3wkO1hkaXLwR9LZoRZIueIxG3GIEB/YMDZUWhD9AR8g="
}"EncryptionSettings": {
"EncryptionKey": "3wkO1hkaXLwR9LZoRZIueIxG3GIEB/YMDZUWhD9AR8g="
}Identity Server can be configured to use a local key (see above) or an Azure Key Vault (see below), just like Orchestrator.
"EncryptionSettings": {
"MultiTenantEncryptionKeyProvider": "AzureKeyVault",
"EncryptionKeyPerTenant": true,
"AzureKeyVaultAddress": "keyVaultAddress",
"AzureKeyVaultCertificateThumbprint": "keyvaultCertificateThumbprint",
"AzureKeyVaultClientId" : "azureClientId"
},"EncryptionSettings": {
"MultiTenantEncryptionKeyProvider": "AzureKeyVault",
"EncryptionKeyPerTenant": true,
"AzureKeyVaultAddress": "keyVaultAddress",
"AzureKeyVaultCertificateThumbprint": "keyvaultCertificateThumbprint",
"AzureKeyVaultClientId" : "azureClientId"
},MultiTenantEncryptionKeyProvider- Indicates in which key management application to store the encryption keys generated per tenant from Orchestrator. By default, the setting hasConfigFileKeyvalue within the code. The accepted values areAzureKeyVaultandConfigFileKey. During Identity Server installation, the value is copied from UiPath.Orchestrator.dll.configEncryptionKeyPerTenant.KeyProvidersetting.
The following Identity Server keys match the Orchestrator keys within
UiPath.Orchestrator.dll.config's SecureAppSettings section:
|
Identity Server Key |
Orchestrator Key |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Important: If CertificatesStoreLocation parameter in
UiPath.Orchestrator.dll.config is set to LocalMachine, make sure that AzureKeyVaultCertificateStoreLocation in appsettings.Production.json has the same value.
Important: If you change the Encryption Key or the Azure Key Vault settings inside Orchestrator’s
UiPath.Orchestrator.dll.config, you must also update Identity Server's appsettings.Production.json with the same values.
The
Logging section configures the log level for each component used by Identity Server. This is a generic logging configuration. Find
more information here.
This section has values within
appsettings.json.
"Logging": {
"LogLevel": {
"Default": "Trace",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
}"Logging": {
"LogLevel": {
"Default": "Trace",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
}Identity Server provides some defaults for a few major components like
Microsoft and Microsoft.Hosting.Lifetime.
The
NLog section is used to define how information is logged in Identity Server via NLog targets, just like in Orchestrator.
This section has values within
appsettings.json.
json
"NLog": {
"IncludeScopes": true,
"throwConfigExceptions": false,
"targets": {
"EventLog": {
"type": "EventLog",
"source": "IdentityService",
"layout": "${longdate} ${logger} ${message}${onexception:${newline}${exception:maxInnerExceptionLevel=10:format=shortType,message,stacktrace:separator=*:innerExceptionSeparator=
	}}"
}
},
"rules": [
{
"logger": "*",
"minLevel": "Info",
"writeTo": "EventLog"
}
]
},json
"NLog": {
"IncludeScopes": true,
"throwConfigExceptions": false,
"targets": {
"EventLog": {
"type": "EventLog",
"source": "IdentityService",
"layout": "${longdate} ${logger} ${message}${onexception:${newline}${exception:maxInnerExceptionLevel=10:format=shortType,message,stacktrace:separator=*:innerExceptionSeparator=
	}}"
}
},
"rules": [
{
"logger": "*",
"minLevel": "Info",
"writeTo": "EventLog"
}
]
},
By default, NLog is configured to write logs to ApplicationEvents. Read here more information about how to configure NLog using a JSON section.
The
AppSettings section is Identity Server's main configuration section. This section has values within appsettings.Production.json and appsettings.json.
-
IdentityServerAddress- Represents the audience that Identity Server checks when validating the token used to call Identity Server API. During installation, this field is automatically populated inside theappsettings.Production.jsonwith Identity Server's address. Do not modify this value because it will break Orchestrator data propagation.This setting has values withinappsettings.Production.jsonandappsettings.json.Note: Make sure to provide a lowercase URL as a value forIdentityServerAddress; otherwise, an error occurs. -
Saml2ValidCertificateOnly- If set totrue, it doesn't allow the use of invalid certificates when configuring SAML2.By default, the setting hastruevalue within the code. -
EnablePII- When set totrue, the exceptions contain sensitive information (for example, the URL address of the external identity provider, or the address of Identity Server, etc.)By default, the setting hasfalsevalue withinappsettings.jsonand the code. HideErrorCodesInUi- Control whether or not login error codes are displayed in the UI. This parameter is not displayed by default. The default value isfalse. Set it totrueto hide login error codes from the UI. For example,"HideErrorCodesInUi": true.-
CookieValidationInterval- Represents the time interval (in seconds) after which the cookie is checked to see if the user and the tenant are still active, and if the user has not logged in another browser. The value withinappsetttings.Production.jsonis automatically migrated from Orchestrator, which has the same setting.By default, the value is set to60seconds withinappsettings.Production.jsonand the code. -
CookieExpireMinutes- Represents the time interval (in minutes) after which the Identity Server cookie expires. The value withinappsetttings.Production.jsonis automatically migrated from Orchestrator, which has the same setting.By default, the value is set to30minutes withinappsettings.Production.jsonand the code. -
OrchestratorUrl- Represents the URL of the Orchestrator. This is where Identity Server redirects you when you click the Orchestrator icon within Identity Management Portal's Hub menu.The value is set during installation withinappsettings.Production.json.Note: Make sure to provide a lowercase URL as a value forOrchestratorUrl; otherwise, an error occurs."AppSettings": { "IdentityServerAddress": "https://myIdentity.domain.local/identity", "EnablePII": false, "HideErrorCodesInUi": true, "CookieExpireMinutes": 30, "OrchestratorUrl": "https://myOrchestratorURL.domain.local" } }"AppSettings": { "IdentityServerAddress": "https://myIdentity.domain.local/identity", "EnablePII": false, "HideErrorCodesInUi": true, "CookieExpireMinutes": 30, "OrchestratorUrl": "https://myOrchestratorURL.domain.local" } }
The
LocalizationSettings section has the following default values within the code:
"LocalizationSettings": {
"EnabledLanguages": "en,ja,de,es,es-MX,fr,ko,pt,pt-BR,ru,tr,zh-CN"
}"LocalizationSettings": {
"EnabledLanguages": "en,ja,de,es,es-MX,fr,ko,pt,pt-BR,ru,tr,zh-CN"
}EnabledLanguages- Lists the languages available in Identity Server. It is used to limit the number of available languages.
The
LoadBalancerSettings section has the following default values within appsettings.Production.json and the code:
"LoadBalancerSettings": {
"RedisConnectionString": "",
"SlidingExpirationTimeInSeconds": 600
}"LoadBalancerSettings": {
"RedisConnectionString": "",
"SlidingExpirationTimeInSeconds": 600
}The values within
appsetttings.Production.json are automatically migrated from Orchestrator's UiPath.Orchestrator.dll.config in case of a multi-node upgrade. If Redis is not configured inside Orchestrator, then appsettings.Production.json will contain this setting.
-
RedisConnectionString- Can only be used ifLoadBalancer.UseRedisis set totrue. A connection string that enables you to set up your Redis server, which contains the URL of the server, the password, and port used with Redis. It is also possible to enable SSL encrypted connections between the Orchestrator nodes and the Redis service. For more information, please click here. Examples:- with SSL enabled -
"RedisConnectionString": A"DOCWREDIS02:6379,password=12345678,ssl=true" - without SSL enabled -
"RedisConnectionString": "DOCWREDIS02:6379,password=12345678"
- with SSL enabled -
SlidingExpirationTimeInSeconds- Controls the sliding expiration time of an item inside the cache. This expiration time applies for both Redis Cache and InMemory Cache (this is the default when Redis is not available).
The
RedisSettings section controls which caches are enabled.
UseRedisStoreCache- Set its value totrueto enable Redis caching of OAuth client data. This helps prevent performance issues when using Interactive Sign In to connect a large number of robots in a short amount of time. This cache uses the same Redis connection string specified in theLoadBalancerSettings. TheUseRedisStoreCachesetting is not displayed by default.
Note: This is not recommended if you are using the External Applications feature since this setting caches clients, and updates to External Applications will not be reflected.
UseRedisStoreClientCache- Set its value totrueto enable Redis caching for first-party clients (UiPath applications) or third-party clients (external applications). If you have a large-scale deployment, it is recommended to enable this flag.
The
SigningCredentialSettings section describes the location of the certificate used to sign the tokens generated by the Identity Server. The values of
the settings in this section are populated by the installer based on your input. The settings can be configured to allow the
reading of the certificate from a certificate store or from Azure Key Vault.
Certificate Rotation Settings
ValidationKeys - Use to indicate your second certificate's Name, Location, and NameType. This is required for certificate rotation.
Note:
For security reasons, the signing certificate must have a 2048-bit public key. Make sure the certificate is valid, unexpired, and Identity Server has access to the private key.
Refer to Certificate Rotation for more on the adjustments you need to make to the
SigningCredentialSettings section to ensure that you always use a certificate within its validity period.
Example of Certificate Store Location Settings
Here's a classic configuration for finding a certificate inside the certificate store:
"SigningCredentialSettings": {
"StoreLocation": {
"Name": "30f3c11e676fc8eb1f9dd4e330f3ce668d796796",
"Location": "LocalMachine",
"NameType": "Thumbprint"
}"SigningCredentialSettings": {
"StoreLocation": {
"Name": "30f3c11e676fc8eb1f9dd4e330f3ce668d796796",
"Location": "LocalMachine",
"NameType": "Thumbprint"
}In this example,
Name represents a Thumbprint value.
We do not recommend using other values for
Location and NameType.
Example of Azure Key Vault Location Settings
"SigningCredentialSettings": {
"AzureKeyVaultLocation": {
"KeyName": "key_name_534553553"
}"SigningCredentialSettings": {
"AzureKeyVaultLocation": {
"KeyName": "key_name_534553553"
}In this example,
KeyName represents the key to search for inside Azure Key Vault.
-
RestrictBasicAuthentication- Enables you to control if users can log in to an Orchestrator instance using basic authentication credentials. This setting is not displayed by default inappsettings.Production.json. The following values are available:true- Users cannot log in using basic authentication credentials.false- Users can log in using basic authentication credentials. This is the default value.
-
EnableBasicAuthenticationForHostTenant- Enables you to control if a host admin can log in to the host tenant of an Orchestrator instance using basic authentication credentials. This setting is not displayed by default in theappsettings.Production.jsonfile. The following values are available:true- The host admin can log in using basic authentication credentials. This is the default value.false- The host admin cannot log in using basic authentication credentials.
This parameter bypasses the
RestrictBasicAuthentication parameter, meaning that if you set EnableBasicAuthenticationForHostTenant to true and RestrictBasicAuthentication to true, you can only log in with basic authentication credentials at the host level.
