Subscribe

UiPath Installation and Upgrade

The UiPath Installation and Upgrade Guide

⚙ 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.json file. This file overrides any pre-existent settings within appsettings.json after each installation process.

📘

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 Priority

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):

  1. Value within the appsettings.Production.json file
  2. Value within the appsettings.json file
  3. Default value set in the code. Used only if a specific setting can't be found within appsettings.Production.json or appsettings.json.

Settings

The appsettings.json file has an internal structure composed of multiple JSON sections separated by a comma.

Connection Strings

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>;"
}

Encryption

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="
}

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"
},
  • MultiTenantEncryptionKeyProvider - Indicates in which key management application to store the encryption keys generated per tenant from Orchestrator. By default, the setting has ConfigFileKey value within the code. The accepted values are AzureKeyVault and ConfigFileKey. During Identity Server installation, the value is copied from UiPath.Orchestrator.dll.config EncryptionKeyPerTenant.KeyProvider setting.

The following Identity Server keys match the Orchestrator keys within UiPath.Orchestrator.dll.config's SecureAppSettings section:

Identity Server Key

Orchestrator Key

EncryptionKeyPerTenant

EncryptionKeyPerTenant.Enabled

AzureKeyVaultAddress

Azure.KeyVault.VaultAddress

AzureKeyVaultCertificateThumbprint

Azure.KeyVault.CertificateThumbprint

AzureKeyVaultClientId

Azure.KeyVault.ClientId

AzureKeyVaultDirectoryId

Azure.KeyVault.DirectoryId

MultiTenantEncryptionKeyProvider

EncryptionKeyPerTenant.KeyProvider

🚧

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.

Logging

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"
  }
}

Identity Server provides some defaults for a few major components like Microsoft and Microsoft.Hosting.Lifetime.

NLog

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.

"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=&#xD;&#xA;&#x9;}}"
    }
  },
  "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.

App Settings

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 the appsettings.Production.json with Identity Server's address. Do not modify this value because it will break Orchestrator data propagation.
    This setting has values within appsettings.Production.json and appsettings.json.

📘

Note:

Make sure to provide a lowercase URL as a value for IdentityServerAddress; otherwise, an error occurs.

  • Saml2ValidCertificateOnly - If set to true, it doesn't allow the use of invalid certificates when configuring SAML2.
    By default, the setting has true value within the code.
  • EnablePII - When set to true, 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 has false value within appsettings.json and 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 is false. Set it to true to 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 within appsetttings.Production.json is automatically migrated from Orchestrator, which has the same setting.
    By default, the value is set to 60 seconds within appsettings.Production.json and the code.
  • CookieExpireMinutes - Represents the time interval (in minutes) after which the Identity Server cookie expires. The value within appsetttings.Production.json is automatically migrated from Orchestrator, which has the same setting.
    By default, the value is set to 60 minutes within appsettings.Production.json and the code.
  • UseRedisStoreCache - Set its value to true to 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 the LoadBalancerSettings. The UseRedisStoreCache setting 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.
  • 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 within appsettings.Production.json.

📘

Note:

Make sure to provide a lowercase URL as a value for OrchestratorUrl; otherwise, an error occurs.

"AppSettings": {
    "IdentityServerAddress": "https://myIdentity.domain.local/identity",
    "EnablePII": false,
    "HideErrorCodesInUi": true,
    "CookieExpireMinutes": 30,
    "OrchestratorUrl": "https://myOrchestratorURL.domain.local"
  }
}

Localization

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"
}
  • EnabledLanguages - Lists the languages available in Identity Server. It is used to limit the number of available languages.

Load Balancer

The LoadBalancerSettings section has the following default values within appsettings.Production.json and the code:

"LoadBalancerSettings": {
  "UseRedis": false,
  "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.

  • UseRedis - Use Redis as a database to distribute messages and cache to and from all the machines connected through your load balancer. This is mandatory for multi-node.
  • RedisConnectionString - Can only be used if LoadBalancer.UseRedis is set to true. 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": "DOCWREDIS02:6379,password=12345678,ssl=true"
    • without SSL enabled - "RedisConnectionString": "DOCWREDIS02:6379,password=12345678"
  • 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).

Signing Credential

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"
  }

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"
  }

In this example, KeyName represents the key to search for inside Azure Key Vault.

Authorization

  • 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 in appsettings.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 the appsettings.Production.json file. 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.

Updated 4 days ago


⚙ Identity Server AppSettings.json


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.