The Orchestrator Credentials Proxy

You can add your own credential stores to Orchestrator, so as to independently control the security of your connection data.

To do that, you can load your desired credential store plugins, in the form of .dll files, to the Orchestrator Credentials Proxy web service. The installation kit contains all plugins supported by UiPath, but you can also develop your own plugin .dll files to load. This service then makes your plugins available to Orchestrator via a proxy, which is created in Orchestrator based on the the public URL and the secret key generated by the proxy.

Known issue

This only applies in scenarios where the Orchestrator Credentials Proxy port is set to a different value than the default 443.

When you upgrade from any version between 1.0.0 and 2.0.1, and you have used a custom port, the local port in the UiPathOrchestratorCredentialsProxy inbound rule is automatically changed to 443, which is the default. This prevents the connection to the proxy from being established.

To work around this, you need to manually change the local port in the inbound rule upon upgrade.

Installation

The Orchestrator Credentials Proxy can be installed either through an .msi installer or through a Docker image provided by UiPath.

Hardware and software requirements

Hardware requirements

These are the minimum requirements for running the proxy on a Windows Server with IIS. The actual resource needs will vary depending on individual usage.

CPU Cores	RAM
2	4 GB

Software requirements

The following Windows Server versions are required for installing the proxy:

• 2012 R2
• 2016
• 2019
• 2022

Through the .msi installer

Prerequisites

The following are required to be able to use the proxy:

• ASP.NET Core versions 3.1, 6.0.x, or 8.0.x
• IIS version 8.0 or higher

• The following Windows features must be installed:

  • IIS-DefaultDocument
  • IIS-HttpErrors
  • IIS-StaticContent
  • IIS-RequestFiltering
  • IIS-URLAuthorization
  • IIS-WindowsAuthentication
  • IIS-ASPNET45
  • IIS-ISAPIExtensions
  • IIS-ISAPIFilter
  • IIS-WebSockets
  • IIS-ApplicationInit
  • IIS-ManagementConsole

Installation steps

Follow these steps to perform the installation:

1. Download the UiPath Orchestrator Credential Proxy installer from the Customer Portal.
2. Install the proxy.

   Connected proxy

   • Public URL - the Orchestrator Credentials Proxy's URL that is publicly exposed
   • SSL Certificate - the Subject or Thumbprint of the SSL certificate used to secure connections with the Orchestrator Credentials Proxy. This is the SSL certificate installed on the computer or web server hosting the proxy.

     Note that it must be issued by a public certificate provider, and it needs to be valid for the Public URL.

   • Port - the port corresponding to the Public URL
   • Secret Key - (automatically generated) the key needed for configuring a custom proxy in the Orchestrator interface; make sure to copy it to your clipboard for future use.

     This can be changed manually, and is also suitable for key rotation.

   Disconnected proxy

   This feature is only available if you are on the Enterprise - Advanced licensing plan.

   • SSL Certificate - the Subject or Thumbprint of the SSL certificate used to secure connections with the Orchestrator Credentials Proxy. This is the SSL certificate installed on the computer or web server hosting the proxy.
   • Port - the port corresponding to the URL
   • Secret Key - (automatically generated) the key needed for configuring a custom proxy in the Orchestrator interface; make sure to copy it to your clipboard for future use.

     This can be changed manually, and is also suitable for key rotation.

   Upon installation, the AppSettings.CredentialsProxyType parameter in the appsettings.Production.json file is set to Disconnected. This is how the proxy detects the type at startup.

Through the Docker image

Preliminary information

All Orchestrator Credentials Proxy settings that can be edited are available in its appsettings.json file. The following parameters are important in the initial setup:

• Jwt:Keys - (initially empty) this array of strings is used to set up the authentication of the proxy. This constitutes the secret key that you will use during the proxy creation process, and that allows Orchestrator to successfully retrieve data from the proxy. Any invalid values are ignored. If no valid values are found, the proxy will not start.

  The secret keys must be in base64 and can be generated by using one of the PowerShell scripts below.

  $bytes = [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(64)
  $jwtSigningKey = [Convert]::ToBase64String($bytes);
  Write-Host $jwtSigningKey

The script above generates 64 random bytes (using SeccureRandom) and converts them to a base64 string.

[Byte[]] $bytes = 1..64
$rng = New-Object System.Security.Cryptography.RNGCryptoServiceProvider
$rng.GetBytes($bytes)
$jwtSigningKey = [Convert]::ToBase64String($bytes);
Write-Host $jwtSigningKey

• appSettings:Plugins.SecureStores - (initially set to the default credential stores available in Orchestrator) this is a CSV string used to specify what .dll assemblies should be loaded from the disk (from path/plugins) in order to enable secure stores to be used by the proxy. Adding invalid assemblies to the list will not break the startup, but you will receive log errors when you try to deploy it.
• appSettings:SigningCredentialSettings:FileLocation:SigningCredential:FilePath and appSettings:SigningCredentialSettings:FileLocation:SigningCredential:Password - (initially hidden) to be used for encrypting the Jwt:Keys and SecureStoreConfigurations:Context parameters. This represents the file path to your signing certificate.
• appSettings:SigningCredentialSettings:StoreLocation:Name, appSettings:SigningCredentialSettings:StoreLocation:Location, appSettings:SigningCredentialSettings:StoreLocation:NameType - (initially hidden) to be used for encrypting the Jwt:Keys and SecureStoreConfigurations:Context parameters.

Encrypting the Jwt:Keys parameter

To add an extra layer of security, you can encrypt the Jwt:Keys and SecureStoreConfigurations:Context parameters in your appsettings.json file.

Note: This requires UiPath.ConfigProtector.exe version 1.0.9 or higher.

Setting up and running the Docker image

To run the Orchestrator Credentials Proxy using Docker, follow the steps below.

1. Download the Docker image

   You can download the image from http://registry.uipath.com/.

   Note that version 1.0.0 only supports the Connected proxy, whereas versions 2.0.0+ also support the Disconnected proxy.

   Use this command to get the image:

   $bytes = [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(64);
   $jwtSigningKey = [Convert]::ToBase64String($bytes);
   docker run -e LICENSE_AGREEMENT=accept -e Jwt__Keys__0=$jwtSigningKey -p 8000:8080 registry.uipath.com/orchestrator-credentialsproxy:1.0.0

   This is the default UiPath image, which contains the credential stores that are already available in your cloud account. You can deploy the image in your cloud environment of choice.

   The command above also generates the secret key.

2. Create your own custom Docker image

   You can create your own Docker image, with additional assemblies, based on the image provided by UiPath and downloaded at step 1. To do that:

   1. Create a new Dockerfile (for illustration purposes, we will name it CustomDockerfile) and add the following to it:

      FROM {docker-image-path}
      RUN rm -rf ./plugins 
      COPY --chown=1001:0 {path of your custom assemblies} ./plugins 
      ENTRYPOINT ["dotnet", "UiPath.OrchestratorCredentialsProxy.dll"]

      • Replace {docker-image-path} with the path to the initial Docker image, provided by UiPath.
      • Replace {path of your custom assemblies} with the path to your own credential store .dll files.

      Find out how Visual Studio uses this Dockerfile to build your images for faster debugging.
   2. Generate the Docker image using this command, which includes the name of the newly created Dockerfile:

      docker build -f CustomDockerfile . -t customproxy

   3. Run the Docker image:

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey -e appSettings__Plugins.SecureStores="{your-list-of-assemblies}" customproxy

      • Replace {your-list-of-assemblies} with the .dll files of the custom credential stores that you want to add to Orchestrator.
      To run the image with one Jwt:Keys parameter:

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey {docker-image-name}

      To run the image with several Jwt:Keys parameters:

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0==$jwtSigningKey" -e Jwt__Keys__1==$jwtSigningKey" -e Jwt__Keys__2==$jwtSigningKey ... {docker-image-name}

      • Replace {docker-image-name} with the name you set for your custom Docker image.

      To run the image with a custom value for the appSettings:Plugins.SecureStores parameter (i.e. with your desired credential store), replace the contents of this parameter with your own credential store .dll files:

      docker run --publish 8000:8080 -e LICENSE_AGREEMENT="accept" -e Jwt__Keys__0=$jwtSigningKey -e appSettings__Plugins.SecureStores="UiPath.Orchestrator.CyberArk.dll;UiPath.Orchestrator.AzureKeyVault.SecureStore.dll" {docker-image-name}

   4. (Optional) Test the new Docker image
      To test your image, access its Swagger interface (http://localhost:8000/swagger/index.html) and check that the endpoints are working.

Configuration

Connected and disconnected proxy

The first step in configuring your proxy is to add any custom .dll plugins that you want to use in the C:\Program Files\UiPath\CredentialsProxy\plugins folder.

Some credential stores may require you to configure settings at the application, host, or proxy level. The settings are equivalent to their Orchestrator counterparts. You must specify these settings in the proxy's appsettings.Production.json file.

CyberArk

You must add any host-level settings such as CLIPasswordSDKExePath, UsePowerShellCLI, and AdditionalAllowedCharacters under the Appsettings parameter in the appsettings.Production.json file:

{
// ...
  "AppSettings": {
    "Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath": "D:\\PathName\\CLIPasswordSDK.exe",
    // ...
  }
  // ...
}

CyberArkCCP

If you cannot retrieve the CyberArkCCP via proxy, add the following parameter in the appsettings.Production.json file:

{
// ...
  "AppSettings": {
    "Plugins.SecureStores.CyberArkCCP.KeyStorageFlags": "MachineKeySet",
    // ...
  }
  // ...
}

Disconnected proxy-only

This proxy type is completely separated from Orchestrator, so you must provide the information related to the credential vaults locally, in the appsettings.Production.json configuration file. You can find the files at the following location: C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.json.

You must edit the following fields in said file, in the AppSettings - SecureStoreConfigurations section:

• Key - the identifier key for the configuration
• Type - the credential vault type, as identified in the .dll files configured via the Plugins.SecureStores parameter found in appsettings.json (see the samples below)
• Context - the connectivity information related to the secure store implementation

Important:

Once you edit the configuration file, you need to restart the service from IIS.

Configuration samples

You need to add the following samples to the appsettings.Production.json configuration file in order to start the disconnected proxy. Otherwise, the service will not start.

Choose the appropriate sample based on your credential store type, or add multiple credential stores by using the very last sample on this page.

AWS Secrets Manager/AWS Secrets Manager (read only)

"SecureStoreConfigurations": [
      {
        "Key": "<MyAwsStore>",
        "Type": "AWS Secrets Manager" / "AWS Secrets Manager (read only)",
        "Context": {
          "UseDefaultCredentials": "true",
          "AccessKey": "<AccessKey>",
          "SecretKey": "<SecretKey>",
          "Region": "<SelectedRegion>"
        }
      },
    ]

Azure Key Vault (read only)

"SecureStoreConfigurations": [
      {
        "Key": "<MyAzureStore>",
        "Type": "AzureKeyVault (read only)",
        "Context": {
          "KeyVaultUri": "<KeyVaultUri>",
          "DirectoryId": "<DirectoryId>",
          "ClientId": "<ClientId>",
          "ClientSecret": "<ClientSecret>"
        }
      },
    ]

Important:

Azure Key Vault (read/write) is not supported.

BeyondTrust Password Safe - Managed Accounts

"SecureStoreConfigurations": [
      {
        "Key": "<MyBeyondTrustManagedAccountsSafe>",
        "Type": "BeyondTrust Password Safe - Managed Accounts",
        "Context": {
          "Hostname": "<HostName>",
          "APIRegistrationKey": "<ApiRegistrationKey>",
          "APIRunAsUsername": "<Username>",
          "DefaultManagedSystemName": "", // can be empty or a string
          "SystemAccountDelimiter": "/", // default account delimiter is "/", but it can be changed
          "ManagedAccountType": "<ManagedAccountType>" // expected value is one of "system", "domainlinked", "database", "cloud", "application"
        }
      },
    ]

BeyondTrust Password Safe - Team Passwords

"SecureStoreConfigurations": [
      {
        "Key": "<MyBeyondTrustTeamPasswordSafe>",
        "Type": "BeyondTrust Password Safe - Team Passwords",
        "Context": {
          "Hostname": "<HostName>",
          "APIRegistrationKey": "<ApiRegistrationKey>",
          "APIRunAsUsername": "<Username>",
          "FolderPathPrefix" : "/", // default delimiter is "/", but it can be changed
          "FolderPasswordDelimiter" : "/" // default delimiter is "/", but it can be changed
        }
      },
    ]

CyberArk - AIM

"SecureStoreConfigurations": [
      {
        "Key": "<MyCyberArk>",
        "Type": "CyberArk",
        "Context": {
          "ApplicationId": "<App_MyCyberArk>",
          "Safe": "<Passwords>",
          "Folder": "<MyFolder>"
        }
      },
    ]

CyberArk - CCP

"SecureStoreConfigurations": [
      {
        "Key": "<MyCyberArkCCPStore>",
        "Type": "CyberArkCCP",
        "Context": {
          "ApplicationId": "<ApplicationId>",
          "Safe": "<CyberArkSafe>",
          "Folder": "<CyberArkFolder>",
          "WebServiceUrl": "<CentralCredentialProviderUrl>",
          "WebServiceName": "<WebServiceName>",
          "SerializedClientCertificate": "<ClientCertificate>", // must be ".pfx" as base64
          "ClientCertificatePassword": "<ClientCertificatePassword>",
          "SerializedRootCA": "<someServerRootCA>" // must be ".crt" or ".cer" as base64
        }
      },
    ]

Based on your IIS configuration, you may need to configure additional KeyStorageFlags as follows:

"AppSettings": {
...
"Plugins.SecureStores.CyberArkCCP.KeyStorageFlags": "MachineKeySet",
...
}

CyberArk® Conjur Cloud (read-only)

"SecureStoreConfigurations": [
      {
        "Key": "MyCyberArkConjur",
        "Type": "CyberArk Conjur Cloud (read only)",
        "Context": {
          "ServiceUrl": "https://{myCyberArkConjurUrl}/",
          "LoginName": "{myLoginName}",
          "ApiKey": "{myApiKey}",
          "VariableIdPrefix": "{myPrefix}"
        }
      },
    ]

HashiCorp Vault / HashiCorp Vault (read only)

"SecureStoreConfigurations": [
      {
        "Key": "<MyHashiCorp>",
        "Type": "HashiCorp Vault" / "HashiCorp Vault (read only)",
        "Context": {
          "VaultUri": "<VaultUri>",
          "AuthenticationType": "<AppRole>",
          "RoleId": "<RoleId>",
          "SecretId": "<SecretId>",
          "Username": "<Username>",
          "Password": "<Password>",
          "Token": "<Token>",
          "SecretsEngine": "<KeyValueV2>",
          "SecretsEngineMountPath": "<Secret>",
          "DataPath": "<applications/orchestrator>",
          "Namespace": "<orchestrator>"
        }
      },
    ]

Thycotic Secret Server

"SecureStoreConfigurations": [
      {
        "Key": "<MyThicoticServer>",
        "Type": "Thycotic Secret Server",
        "Context": {
          "SecretServerUrl": "<ServerUrl>",
          "RuleName": "<Rule>",
          "RuleKey": "<Key>",
          "UsernameField": "<Username>",
          "PasswordField": "<Password>"
        }
      },
    ]

Multiple credential stores

If you use multiple credential stores, you can add one under the other, as follows:

{
...
  "AppSettings": {
  ...
    "SecureStoreConfigurations": [
      {
        "Key": "<SecureStoreKey1>",
        "Type": "AzureKeyVault (read only)",
        "Context": {
          "KeyVaultUri": "<Uri>",
          "DirectoryId": "<DirectoryId>",
          "ClientId": "<ClientId>",
          "ClientSecret": "<ClientSecret>"
        }
      },
      {
        "Key": "<SecureStoreKey2>",
        "Type": "BeyondTrust Password Safe - Managed Accounts",
        "Context": {
          "Hostname": "<Host>",
          "APIRegistrationKey": "<ApiKey>",
          "APIRunAsUsername": "<ApiUsername>",
          "DefaultManagedSystemName": "",
          "SystemAccountDelimiter": "/",
          "ManagedAccountType": "system"
        }
      }
    ]
  ...
  }
}

Validation

Important:

This only applies to the disconnected credentials proxy.

The proxy validates the configuration on startup, if the type it detects is Disconnected.

These are some of the validation steps the proxy performs:

• The proxy ensures that that appsettings.Production.json contains the expected configurations, as detailed in the Configuration section above.
• The proxy ensures that SecureStoreConfigurations does not contain any duplicate Key parameters, i.e. that the credential stores configured in the appsettings.Production.json file are unique.

• The SecureStoreConfigurations parameter is an array of configurations. You can add as many credential stores as you want, even of the same type. For example, you can have multiple Azure Key Vault (read only) instances configured, as long as the Key field is unique.

• The proxy checks that all Type values are valid.

• Based on the implementation of each secure store, the proxy checks that the vault can be reached successfully.

Logging

Orchestrator Credentials Proxy logs are stored locally, in the C:\Program Files\UiPath\OrchestratorCredentialsProxy folder, if the proxy's application pool has write permissions for that path. These are configured in IIS.

If you do not want to give write permissions to that folder, provide a relative or absolute path of your choice via the NLog.targets.logfile.fileName parameter in appsettings.Production.json.

On Windows machines, the proxy also stores logs in the Windows Event Viewer.

Security considerations

• Orchestrator only allows secure (HTTPS) URLs for the proxy. The HTTPS certificate must be valid and signed by a widely recognized certificate authority. Certificates that are self-signed or signed by an internal authority are not supported.
• Orchestrator is validated through a client secret generated by the Orchestrator Credentials Proxy. The client secret is stored in a configuration file on the machine where the Orchestrator Credentials Proxy is installed, and it is encrypted and stored in the database by Orchestrator.
• When you edit a credential store proxy in Orchestrator and changing its URL, you must enter the client secret.

• Orchestrator Credentials Proxy 2.0.0+ actions are logged in the Windows Event Viewer.

• Binaries must be signed on the Windows machine.
• The Docker image must be signed.

Using the Orchestrator Credentials Proxy with a load balancer

If you use the proxy in combination with a load balancer, make sure that you maintain the same configuration across all nodes.

Elements that must remain identical across nodes

• The proxy installer version. For example, if you use version 1.0.0, then all load balancer nodes need to use 1.0.0 as well.
• The settings in the application configuration files. In most cases, these are appsettings.json and appsettings.Production.json. Note that appsettings.Production.json is unique for each installation, so you must manually add it to each node in order to ensure consistency.
• The credential store plugins added to path/plugins. All plugins supported by us are already in this folder, so you only need to be mindful of any custom plugins you add.

Important things to consider

• If you want to make any changes to the Docker image configuration, we provide for installing the proxy, we highly recommend that you create a custom Docker image instead. You should then use this custom image to deploy the proxy on all nodes.
• Some environment variables can have an impact at runtime. For example, environment variables that override appsettings.json configuration values or those that affect .NET environment.
• You can use the https://{YourOrchestratorCredentialsProxyURL}/api/v1/Health dedicated unauthenticated endpoint to check if the Orchestrator Credentials Proxy is still running.

Updating the Orchestrator Credentials Proxy certificate

For single-node installations, update the SSL certificate as follows:

1. Import the new certificate into the Personal folder, under Certificates, in the local machine's certificate console (certlm.msc).
2. In the IIS Management Console, expand Sites, and select UiPath Orchestrator Credential Proxy.
3. From the right-side panel, select Bindings....
4. From the Bindings... view, select the default https record, then use the Select... button to choose a certificate.
5. In the Select Certificate pop-up window, select the newly added certificate.
6. Select OK until you complete the setup.

Note:

For multi-node installations, make sure you update the certificate on all machines.

To update the certificate for installations using a load balancer, use the same steps described above. Since Orchestrator Credentials Proxy is stateless, remove the node from the load balancer when updating the certificate.