Orchestrator Credentials Proxy

Orchestrator に独自の資格情報ストアを追加することで、接続データのセキュリティを独自に制御できます。

そのためには、必要な資格情報ストア プラグインを .dll ファイルの形式で、Orchestrator の Credentials Proxy Web サービスに読み込みます。インストール キットには UiPath がサポートするすべてのプラグインが含まれていますが、独自のプラグイン .dll ファイルを開発して読み込むこともできます。その後、プラグインはプロキシ経由でサービスによって Orchestrator に対して利用可能になります。プロキシは、パブリック URL とプロキシで生成されたシークレット キーに基づいて Orchestrator で作成されます。

既知の問題

これは、Orchestrator Credentials Proxy のポートが既定の 443 と異なる値に設定されている場合にのみ適用されます。

1.0.0 から 2.0.1 までの任意のバージョンからアップグレードするときに、カスタム ポートを使用していても、受信規則 UiPathOrchestratorCredentialsProxy のローカル ポートが自動的に 443 (既定値) に変更されます。これにより、プロキシへの接続が確立されなくなります。

この問題を回避するには、アップグレード時に受信規則のローカル ポートを手動で変更する必要があります。

インストール

Orchestrator Credentials Proxy は、UiPath が提供する .msi インストーラー、または Docker イメージを使用してインストールできます。

ハードウェアおよびソフトウェアの要件

ハードウェア要件

IIS が搭載されている Windows Server でプロキシを実行するための最小要件は、以下のとおりです。実際に必要なリソースは、個々の使用状況によって異なります。

CPU コア	RAM
2	4 GB

ソフトウェア要件

プロキシのインストールには、次のバージョンの Windows Server が必要です。

• 2012 R2
• 2016
• 2019
• 2022 年

.msi インストーラーを使用する

前提条件

プロキシを使用するには以下が必要です。

• ASP.NET コア バージョン 3.1、6.0.x、または 8.0.x
• バージョン 8.0 以上の IIS

• Windows の次の機能をインストールする必要があります。

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

インストールの手順

インストールを実行するには、以下の手順に従います。

1. Customer Portal から UiPath Orchestrator Credential Proxy インストーラーをダウンロードします。
2. プロキシをインストールします。

   接続状態のプロキシ

   • パブリック URL - パブリックに公開されている Orchestrator Credentials Proxy の URL です。
   • SSL 証明書 - Orchestrator Credentials Proxy との接続をセキュリティで保護するために使用される SSL 証明書のサブジェクトまたは拇印です。これは、プロキシをホストするコンピューターまたは Web サーバーにインストールされた SSL 証明書です。

     パブリックな証明書プロバイダーによって発行される必要があり、パブリック URL に対して有効である必要がありますのでご注意ください。

   • ポート - パブリック URL に対応するポートです。
   • シークレット キー - Orchestrator のインターフェイスでカスタム プロキシを構成するのに必要なキー (自動生成) です。後で使用できるよう、クリップボードにコピーしておいてください。

     これは手動で変更できて、キー ローテーションにも適しています。

   非接続のプロキシ

   この機能は、Enterprise - Advanced ライセンス プランでのみ利用できます。

   • SSL 証明書 - Orchestrator Credentials Proxy との接続をセキュリティで保護するために使用される SSL 証明書のサブジェクトまたは拇印です。これは、プロキシをホストするコンピューターまたは Web サーバーにインストールされた SSL 証明書です。
   • ポート - URL に対応するポートです。
   • シークレット キー - Orchestrator のインターフェイスでカスタム プロキシを構成するのに必要なキー (自動生成) です。後で使用できるよう、クリップボードにコピーしておいてください。

     これは手動で変更できて、キー ローテーションにも適しています。

   インストール時に、appsettings.Production.json ファイルの AppSettings.CredentialsProxyType パラメーターは Disconnected に設定されます。これによって、プロキシは起動時に接続/非接続を検出します。

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 で利用可能な既定の資格情報ストアに設定) これは、プロキシによる Secure Store の使用を有効化するために、ディスク (path/plugins) から読み込むべき .dll アセンブリを指定する目的で使用される CSV 文字列です。無効なアセンブリをリストに追加してもスタートアップは破損しませんが、デプロイしようとするとログのエラーが発生します。
• 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 v1.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 イメージを作成する

   手順 1 でダウンロードした、UiPath が提供するイメージに基づいて、追加のアセンブリを含む独自の 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 ファイルに置き換えます。
      1 つの 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 ファイルで指定する必要があります。

CyberArk

appsettings.Production.json ファイルの Appsettings パラメーターの下に、CLIPasswordSDKExePath、UsePowerShellCLI、AdditionalAllowedCharacters などのホスト レベルの設定を追加する必要があります。

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

CyberArk CCP

プロキシ経由で CyberArkCCP を取得できない場合は、 appsettings.Production.json ファイルに次のパラメーターを追加します。

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

非接続のプロキシのみ

この種類のプロキシは Orchestrator から完全に分離されているため、資格情報コンテナーに関する情報をローカルの appsettings.Production.json 構成ファイルで指定する必要があります。 ファイルは、 C:\Program Files\UiPath\OrchestratorCredentialsProxy\appsettings.Production.jsonにあります。

上記のファイルの [ AppSettings - SecureStoreConfigurations ] セクションで、以下のフィールドを編集する必要があります。

• Key - 設定の識別子キーです。
• Type - appsettings.json で Plugins.SecureStores パラメーターを使用して設定された .dll ファイルで識別される資格情報コンテナーの種類です (以下のサンプルを参照)。
• Context - Secure Store の実装に関連する接続情報です。

重要:

設定ファイルを編集したら、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 Key Vault (読み取り専用)

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

重要:

Azure Key Vault (読み取り/書き込み) はサポートされていません。

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

IIS の設定によっては、以下のように追加の KeyStorageFlags を設定する必要がある場合があります。

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

CyberArk® Conjur Cloud (読み取り専用)

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

HashiCorp Vault/HashiCorp Vault (読み取り専用)

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

複数の資格情報ストア

複数の資格情報ストアを使用する場合は、以下のように 1 つの資格情報ストアを並べて追加できます。

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

検証

重要:

これは、非接続の資格情報プロキシにのみ適用されます。

プロキシは、検出した種類が Disconnectedの場合、起動時に設定を検証します。

以下に、プロキシが実行する検証手順の一部を示します。

• プロキシは、上記の「設定」セクションで詳しく説明しているように、appsettings.Production.jsonに予期される設定が含まれていることを確認します。
• プロキシは、 SecureStoreConfigurations に重複する Key パラメーターが含まれないように、つまり、 appsettings.Production.json ファイルで設定された資格情報ストアが一意であることを保証します。

• SecureStoreConfigurations パラメーターは、設定の配列です。資格情報ストアは、同じ種類のものであっても、必要な数だけ追加できます。 たとえば、 Key フィールドが一意である限り、複数の Azure Key Vault (読み取り専用) インスタンスを設定できます。

• プロキシは、すべての Type 値が有効であることを確認します。

• プロキシは、各 Secure Store の実装に基づいて、コンテナーに正常に到達できることを確認します。

ログ

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に追加された資格情報ストア プラグイン。UiPath がサポートするプラグインはすべてすでにこのフォルダーにあるため、注意が必要なのは追加するカスタム プラグインだけです。

考慮すべき重要事項

• Docker イメージの構成に変更を加える場合は、プロキシのインストールのために用意されていますが、代わりにカスタム Docker イメージを作成することを強くお勧めします。 次に、このカスタム イメージを使用して、すべてのノードにプロキシをデプロイする必要があります。
• 一部の環境変数は、実行時に影響を与える可能性があります。 たとえば、 appsettings.json 構成値をオーバーライドする環境変数や、.NET 環境に影響を与える環境変数などです。
• https://{YourOrchestratorCredentialsProxyURL}/api/v1/Health 専用の非認証エンドポイントを使用して、Orchestrator Credentials Proxy がまだ実行中かどうかを確認できます。

Orchestrator Credentials Proxy の証明書を更新する

シングルノードのインストールの場合は、次の手順で SSL 証明書を更新します。

1. 新しい証明書を、ローカル マシンの証明書コンソール (certlm.msc) の [証明書] の下にある [個人] フォルダーにインポートします。
2. IIS 管理コンソールで、[サイト] を展開して [UiPath Orchestrator Credential Proxy] を選択します。
3. 右側のパネルから [バインド...] を選択します。
4. [バインド...] ビューから既定の https レコードを選択し、[選択...] ボタンを使用して証明書を選択します。
5. [証明書の選択] ポップアップ ウィンドウで、新しく追加した証明書を選択します。
6. セットアップが完了するまで [OK] を選択します。

注:

マルチノードのインストールの場合は、必ずすべてのマシンで証明書を更新してください。

ロード バランサーを使用しているインストールの証明書を更新するには、上記と同じ手順を使用します。Orchestrator Credentials Proxy はステートレスであるため、証明書を更新する際はロード バランサーからノードを削除してください。