Orchestrator Credentials Proxy

您可以将自己的凭据存储添加到 Orchestrator，以便独立控制连接数据的安全性。

为完成此操作，您可以以 .dll 文件的形式将所需的凭据存储插件加载到Orchestrator Credentials Proxy 网页服务。安装工具包包含 UiPath 支持的所有插件，但您也可以开发自己的插件 .dll 文件以用于加载。此服务然后通过代理将您的插件部署到 Orchestrator，该代理是根据公共 URL 和代理生成的密钥在 Orchestrator 中创建。

安装

Orchestrator 凭据代理可以通过 .msi 安装程序或通过 UiPath 提供的 Docker 映像完成安装。

通过 .msi 安装程序

先决条件

要使用代理，需要满足以下条件：

• ASP.NET Core 版本 3.1 或 6.0.x
• IIS 8.0 或更高版本

• 必须安装以下 Windows 功能：

  • IIS 默认文档
  • IIS Http 错误
  • IIS 静态内容
  • IIS 请求筛选
  • IIS URL 授权
  • IIS Windows 身份验证
  • IIS ASPNET45
  • IIS ISAPI 扩展程序
  • IIS ISAPI 筛选器
  • IIS WebSocket
  • IIS 应用程序初始化
  • IIS 管理控制台

硬件和软件要求

硬件要求

以下是在具有 IIS 的 Windows Server 上运行代理的最低要求：

CPU 核心	RAM
2	4GB

软件要求

安装代理需要以下 Windows Server 版本：

• 2012 R2
• 2016 年
• 2019 年
• 2022

安装步骤

请按照以下步骤执行安装：

1. 前往 Customer Portal 下载 UiPath Orchestrator 凭据代理安装程序。
2. 安装代理。

   已连接的代理

   • 公共 URL - 公开的 Orchestrator Credentials Proxy URL

   • SSL 证书 - 用于保护与 Orchestrator Credentials Proxy 连接的 SSL 证书主题或指纹。这是安装在托管代理的计算机或网页服务器上的 SSL 证书。

     请注意，它必须对公共 URL 有效。

   • 端口 - 与公共 URL 对应的端口
   • 密钥 -（自动生成）在 Orchestrator 界面中配置自定义代理所需的密钥；请务必将其复制到剪贴板以备将来使用。

     这可以手动更改，也适用于密钥轮换。

   已断开代理连接

   仅当您订阅企业版 - 高级许可计划时，才可以使用此功能。

   • SSL 证书 - 用于保护与 Orchestrator Credentials Proxy 的连接的 SSL 证书。这是安装在托管代理的计算机或网页服务器上的 SSL 证书。

   • 端口 - 与 URL 对应的端口

   • 密钥 -（自动生成）在 Orchestrator 界面中配置自定义代理所需的密钥；请务必将其复制到剪贴板以备将来使用。

   安装完成后，appsettings.Production.json 文件中的 AppSettings.CredentialsProxyType 参数设置为“已断开连接”。这就是代理在启动时检测类型的方式。

通过 Docker 映像

初步信息

所有可编辑的 Orchestrator Credentials Proxy 设置都可在其 appsettings.json 文件中找到。以下参数在初始设置中非常重要：

• Jwt:Keys -（最初为空）此字符串数组用于设置代理的身份验证。该数组构成您将在代理创建过程中使用的密钥，并允许 Orchestrator 成功从代理检索数据。系统将忽略任何无效值。如果未找到有效值，则代理将不会启动。

  密钥必须采用 base64 格式，并且可以通过以下任一 PowerShell 脚本生成。

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

上述脚本会生成 64 个随机字节（使用 SeccureRandom），并将这些字节转换为 Base64 字符串。

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

• appSettings:Plugins.SecureStores -（最初设置为 Orchestrator 中可用的默认凭据存储）这是一个 CSV 字符串，用于指定应从磁盘（从 path/plugins）加载哪些 .dll 程序集，以便代理使用安全存储。将无效程序集添加到列表中不会中断启动，但在尝试部署程序集时会收到日志错误。
• appSettings:SigningCredentialSettings:FileLocation:SigningCredential:FilePath 和 appSettings:SigningCredentialSettings:FileLocation:SigningCredential:Password -（最初隐藏）用于加密 Jwt:Keys 和 SecureStoreConfigurations:Context 参数。这表示签名证书的文件路径。
• appSettings:SigningCredentialSettings:StoreLocation:Name、appSettings:SigningCredentialSettings:StoreLocation:Location、appSettings:SigningCredentialSettings:StoreLocation:NameType -（最初隐藏）用于加密 Jwt:Keys 和 SecureStoreConfigurations:Context 参数。

加密 Jwt:Keys 参数

要增加额外的安全性，您可以加密 appsettings.json 文件中的 Jwt:Keys 和 SecureStoreConfigurations:Context 参数。

注意：此操作需要 UiPath.ConfigProtector.exe 版本为 1.0.9 或更高版本。

设置并运行 Docker 映像

要使用 Docker 运行 Orchestrator Credentials Proxy，请按照以下步骤操作。

1. 下载 Docker 映像

   您可以从 http://registry.uipath.com/ 下载映像。

   请注意，1.0.0 版本仅支持“已连接代理”，而 2.0.0 版本还支持“已断开连接代理”。

   使用以下命令获取映像：

   $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

   这是默认的 UiPath 映像，其中包含云帐户中已提供的凭据存储。您可以在选择的云环境中部署映像。

   上述命令还会生成密钥。

2. 创建您自己的自定义 Docker 映像

   您可以根据 UiPath 提供并在步骤 1 中下载的映像，创建自己的 Docker 映像以及其他程序集。为完成此操作，请执行以下操作：

   1. 创建一个新的 Dockerfile（为了便于说明，我们将其命名为 CustomDockerfile）并向其中添加以下内容：

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

      • 将 {docker-image-path} 替换为 UiPath 提供的初始 Docker 映像的路径。
      • 将 {path of your custom assemblies} 替换为您自己的凭据存储 .dll 文件的路径。

      了解 Visual Studio 如何使用此 Dockerfile 来构建映像以加快调试速度。
   2. 使用以下命令生成 Docker 映像，其中包括新创建的 Dockerfile 的名称：

      docker build -f CustomDockerfile . -t customproxy

   3. 运行 Docker 映像：

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

      • 将 {your-list-of-assemblies} 替换为要添加到 Orchestrator 的自定义凭据存储 .dll 文件。
      要使用一个 Jwt:Keys 参数运行映像，请执行以下操作：

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

      要使用多个 Jwt:Keys 参数运行映像，请执行以下操作：

      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}

      • 将 {docker-image-name} 替换为您为自定义 Docker 映像设置的名称。

      要使用 appSettings:Plugins.SecureStores 参数的自定义值（即使用所需的凭据存储）运行映像，请将此参数的内容替换为您自己的凭据存储 .dll 文件：

      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. （可选）测试新的 Docker 映像
      要测试映像，请访问其 Swagger 界面 (http://localhost:8000/swagger/index.html)，并检查端点是否正常工作。

配置

配置代理的第一步是将自定义 .dll 要在 C:\Program Files\UiPath\CredentialsProxy\plugins 文件夹中使用的插件。

接下来的步骤仅适用于已断开连接代理，因为已连接的代理不需要专用配置。

已断开代理连接

此代理类型完全独立于 Orchestrator，因此您必须在 appsettings.Production.json 配置文件中（位于以下位置）以本地方式提供与凭据保险库相关的信息：C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.json。

这些是需要在所述文件中的“AppSettings > SecureStoreConfigurations”部分中编辑的字段：

• Key - 适用于配置的标识符密钥
• Type - .dll 文件中标识的凭据保险库类型，该 .dll 文件通过 appsettings.json 中的 Plugins.SecureStores 参数完成配置（请参阅下方的示例）
• Context - 与安全存储实现相关的连接信息

重要提示：

编辑配置文件后，您需要从 IIS 重新启动服务。

配置示例

您需要将这些示例添加到 appsettings.Production.json 配置文件中，以便启动已断开连接的代理。否则，该服务将不会启动。

根据您的凭据存储类型选择适当的示例，或使用此页面上的最后一个示例添加多个凭据存储。

AWS Secrets Manager/AWS Secrets Manager（只读）

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

Azure 密钥保险库（只读）

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

重要提示：

不支持密钥保险库（读取/写入）。

BeyondTrust 密码保险箱 - 托管帐户

"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 密码保险箱 - 团队密码

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

根据 IIS 配置，您可能需要配置其他 KeyStorageFlags，如下所示：

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

HashiCorp 保险库 /HashiCorp 保险库（只读）

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

多个凭据存储

如果使用多个凭据存储，则可以将它们逐个添加，如下所示：

{
...
  "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"
        }
      }
    ]
  ...
  }
}

验证

重要提示：

这仅适用于已断开连接的 Credentials Proxy。

如果代理检测到的类型为 Disconnected，则它会在启动时验证配置。

以下是要执行的一些验证步骤：

• 它可确保 appsettings.Production.json 包含预期配置，如上面的“配置”部分中所述。
• 它可确保 SecureStoreConfigurations 不包含任何重复的 Key 参数，即 appsettings.Production.json 文件中配置的凭据存储是唯一的。

• SecureStoreConfigurations 参数是一个配置数组，这意味着您可以根据需要添加任意数量的凭据存储，即使类型相同。例如，您可以配置多个 Azure 密钥保险库（只读）实例，前提是 Key 字段唯一。

• 它会检查所有 Type 值是否有效。

• 它会根据每个安全存储的实施情况，检查是否可以成功访问保险库。

日志记录

如果代理的应用程序池具有该路径的写入权限，则 Orchestrator Credentials Proxy 日志会存储在本地的 C:\Program Files\UiPath\OrchestratorCredentialsProxy 文件夹中。系统会在 IIS 中配置这些内容。

如果您不想授予该文件夹写入权限，则可以通过 appsettings.Production.json 中的 NLog.targets.logfile.fileName 参数提供您选择的相对或绝对路径。

在 Windows 计算机上，代理还将日志存储在 Windows 事件查看器中。

安全注意事项

• Orchestrator 仅允许针对代理使用安全 (HTTPS) URL。HTTPS 证书必须有效，并由广泛认可的证书颁发机构签名。不支持自签名证书或由内部授权机构签名的证书。
• Orchestrator 通过 Orchestrator Credentials Proxy 生成的客户端密码进行验证。客户端密码存储在安装 Orchestrator Credentials Proxy 计算机的配置文件中，并由 Orchestrator 加密并存储在数据库中。
• 在 Orchestrator 中编辑凭据存储代理并更改其 URL 时，您还需要输入客户端密码。

• Orchestrator Credentials Proxy 2.0.0 及更高版本操作记录在 Windows 事件查看器中。

• 必须在 Windows 计算机上签二进制。
• 必须对 Docker 映像进行签名。

将 Orchestrator Credentials Proxy 与负载均衡器一起使用

您可以将代理与负载均衡器结合使用，前提是确保在所有节点上维持相同的配置。

必须在节点之间保持元素相同

• 代理安装程序版本。例如，如果您使用 1.0.0 版本，则所有负载均衡器节点也需要使用 1.0.0 版本。
• 应用程序配置文件中的设置。在大多数情况下，为 appsettings.json 和 appsettings.Production.json。请注意，appsettings.Production.json 对于每次安装都是唯一的，因此您必须手动将其添加到每个节点以确保一致性。
• 已将凭据存储插件添加到 path/plugins。我们支持的所有插件都已在此文件夹中，因此您主要需要注意添加的任何自定义插件。

需要考虑的重要事项

• 如果您想对我们提供的用于安装代理的 Docker 映像的配置进行任何更改，我们强烈建议您改为创建自定义 Docker 映像。然后，您应该使用此自定义映像在所有节点上部署代理。
• 某些环境变量（例如覆盖 appsettings.json 配置值的变量或影响 .NET 环境的变量）可能会在运行时产生影响。
• 您可以使用 https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/api/v1/Health 专用的未经身份验证的端点来检查 Orchestrator Credentials Proxy 是否仍在运行。