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.

Installation

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

Through the .msi installer

Prerequisites

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

• ASP.NET Core versions 3.1 or 6.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

Hardware and software requirements

Hardware requirements

These are the minimum requirements for running the proxy on a Windows Server with IIS:

CPU Cores	RAM
2	4 GB

Software requirements

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

• 2012 R2
• 2016
• 2019
• 2022

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 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 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.

   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 version 2.0.0 also supports 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

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.

The next steps only apply to the disconnected proxy, since the connected proxy does not require dedicted configuration.

Disconnected proxy

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, found at the following location: C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.json.

These are the fields that need to be edited 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

These are samples that you need to add to the appsettings.Production.json configuration file in order to start the disconnected proxy. If you do not, 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 might need to configure additional KeyStorageFlags as follows:

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

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 them 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 that are performed:

• It ensures that that appsettings.Production.json contains the expected configurations, as detailed in the Configuration section above.
• It 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, which means that 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.

• It checks that all Type values are valid.

• Based on the implementation of each secure store, it 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, you can 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 is encrypted and stored in the database by Orchestrator.
• When editing a credential store proxy in Orchestrator and changing its URL, you are also required to 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

You can use the proxy in combination with a load balancer, as long as you 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 mainly need to be mindful of any custom plugins you add.

Important things to consider

• If you want to make any changes to the configuration of the Docker image 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 enviroment variables, such as those that override appsettings.json configuration values or those that affect .NET environment, can have an impact at runtime.
• You can use the https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/api/v1/Health dedicated unauthenticated endpoint to check whther the Orchestrator Credentials Proxy is still running.