カスタム証明書を信頼する

カスタム証明書を信頼する

CLI では、認証されるすべてのコマンドで 2 つのパラメーターを任意で指定できます。このパラメーターを使用すると、Orchestrator と Identity Server の TLS 証明書の検証方法を制御できます。このアクティビティは、オペレーティング システムがまだ信頼していないプライベート (内部、自己署名) 証明機関によってホスト証明書が署名されている UiPath Automation Suite やその他の Orchestrator デプロイに接続する場合に最も役立ちます。

どちらのパラメーターも指定しない場合、CLI は以前とまったく同じように動作し、サーバー証明書をオペレーティング システムの信頼ストアと照合して検証します。以下で説明するパラメーターは加算です。それらは信頼の決定を延長または制約しますが、決してそれを弱めることはありません。

--ca-certパラメーター

1 つ以上の信頼されたルート CA 証明書ファイルを信頼の決定に追加します。オペレーティングシステムがすでに信頼しているものは何でも機能し続けます。ここで提供する証明書は、それに加えて受け入れられます。

構文

--ca-cert <path>
--ca-cert <path1>,<path2>,...
--ca-cert <path1> --ca-cert <path2>

サポートされている証明書ファイル形式

形式	一般的な拡張機能	備考
Pem	.pem.crt、.cer	-----BEGIN CERTIFICATE-----マーカー付きのテキスト形式。1 つのファイルには、複数の連結された証明書 (「バンドル」) を含めることができます。
デア	.der.cer、.crt	バイナリ X.509。1 つのファイルにつき 1 つの証明書。
PKCS#7	.p7b, .p7c	秘密キーを使用しない証明書コレクション。既定では、Windows 証明書マネージャー (certmgr.msc) がエクスポートする形式です。

この形式は、拡張子からではなく、ファイルの内容から自動検出されます - PEMブロックを含む .cer ファイルとDERバイトを含む .cer ファイルの両方が処理されます。

サポート対象外: PFX/PKCS#12 (.pfx、 .p12).これらのファイルは秘密鍵を運び、トラストアンカーとしてではなく、クライアントIDを意図しています。CLI は、明示的なエラーで拒否します。

複数の証明書

必要な数のルートを提供できます。フラグは、繰り返すことも、コンマで区切ることも、両方の形式を組み合わせることもできます。以下の 3 つのコマンドは同等です。

--ca-cert "C:\certs\as-root.pem" --ca-cert "C:\certs\corp-root.pem"
--ca-cert "C:\certs\as-root.pem,C:\certs\corp-root.pem"
--ca-cert "C:\certs\bundle.pem"

3 番目の形式では、 bundle.pem 両方の証明書が連結された 1 つの PEM ファイルです。

---

--pinnedpubkeyパラメーター

サーバー リーフ証明書の公開キーを特定の SHA-256 ハッシュにピン留めします。形式は curl 互換です: リテラル文字列 sha256// 、その後に証明書の SubjectPublicKeyInfo の base64 でエンコードされた SHA-256 が続きます。

構文

--pinnedpubkey "sha256//<base64 hash>"

ピンは、標準の証明書の検証 に加えて チェックされますが、代わりにチェックされません。証明書は引き続き信頼できるルートにチェーンされ、ホスト名のチェックに合格する必要があります。その上、公開キーは PIN と一致する必要があります。両方の条件が必要です - curlの動作と一致します。

チェーンの検証以外にピン留めで追加されるもの

チェーン検証だけでも、「これらのCAによって署名されたすべての証明書を信頼する」と表示されます。ピンは次のように付け加えています 。ただし、公開鍵がこの正確なハッシュと一致する場合に限ります。」各レイヤーで異なる脅威が捕捉されます。

脅威	チェーンのみ	チェーン+ピン
CA が発行した証明書を持たないランダムな攻撃者	ブロック中	ブロック中
システムがすでに信頼しているCAからの証明書を持つ攻撃者(たとえば、公的CAの誤発行または侵害)	承認	ブロック中
独自の CA が同じホスト名に対して新しい証明書を発行し、同じキーを再利用します (正当な更新)	承認	承認
独自の CA が、同じホスト名に対して 異なる キーで新しい証明書を発行します (キーの再設定または攻撃)	承認	ブロック中

ピン留めが運用コストに見合う場合:

• 公的に信頼できるサーバーでの多層防御。Orchestrator が公的に発行された証明書を使用している場合、チェーン検証は、オペレーティング システムが信頼する、そのホスト名に対して発行することを決定した ~150 個の公的 CA のいずれかの証明書を受け入れます。ピンは、受け入れる予定の証明書に絞り込みます。
• 社内のCAチームを完全に信頼していない。リーフの公開キーをピン留めすると、CA の署名機関全体ではなく、受け入れる予定の 1 つの証明書に信頼が絞り込まれます。

ピン留めがやり過ぎの場合:

• 完全に制御するプライベート CA に対して --ca-cert をすでに使用しています。チェーン アンカーはクラスターのリーフに署名するのと同じルートであり、2 番目の CA は機能しないため、ピン留めにより、セットアップで発生しない攻撃クラス (不正な CA 発行の証明書) が防止されます。

SHA-256ピンの入手方法

ピンは、証明書の SubjectPublicKeyInfo (SPKI)の SHA-256 ハッシュで、base64 でエンコードされ、プレフィックスが sha256//が付けられます。SPKIは、公開鍵とそのアルゴリズム識別子を保持するX.509証明書の一部であり、完全な証明書ではなく、生のモジュラスだけではありません。

完全な証明書ではなく SPKI をピン留めすると、サーバーが同じキーで証明書を再発行(更新)しても、ピンは一致します。ピンを変更する必要があるのは、サーバーが実際に新しいキーペアにローテーションするときだけです。

ピンは、アクセス権に応じて 3 つの方法で計算できます。

証明書ファイル(PEM、DER、または .cer)から

PowerShell - すぐに使える Windows で動作し、追加のツールは必要ありません。

$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new(
    'C:\certs\orchestrator-leaf.cer')
$spki = $cert.PublicKey.ExportSubjectPublicKeyInfo()
$hash = [System.Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

出力例:

sha256//5FAF491D9F7AC8274B1353B9E2E9317733033EFC22341ABAEA6466037D5123EE=

OpenSSL - OpenSSL がインストールされた Linux、macOS、Windows で動作します。

openssl x509 -in cert.pem -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

次に、結果の base64 文字列の先頭に sha256// を追加します。ファイルが DER 形式 (バイナリ) の場合は、最初のコマンドに -inform der を追加します。

openssl x509 -in cert.der -inform der -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

ライブサーバーから直接

証明書ファイルはないが、サーバーに到達可能な場合は、TLS ハンドシェイク自体を使用して証明書ファイルを取得します。

Openssl：

HOST=orchestrator.your-cluster.internal
openssl s_client -servername $HOST -connect $HOST:443 < /dev/null 2>/dev/null |
  openssl x509 -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

PowerShell (openssl は不要):

$h = 'orchestrator.your-cluster.internal'
$tcp = [Net.Sockets.TcpClient]::new($h, 443)
$cb  = [Net.Security.RemoteCertificateValidationCallback]{ param($s,$c,$ch,$e) $script:cert=$c; $true }
$ssl = [Net.Security.SslStream]::new($tcp.GetStream(), $false, $cb)
$ssl.AuthenticateAsClient($h); $ssl.Close(); $tcp.Close()
$cert2 = [Security.Cryptography.X509Certificates.X509Certificate2]::new($script:cert)
$spki  = $cert2.PublicKey.ExportSubjectPublicKeyInfo()
$hash  = [Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

ライブサーバーから取得する利点は、証明書ファイルを見つけてエクスポートする必要がないことです - サーバーがポート 443 で提示するものは、CLI が認識して検証するものです。

Windows 信頼ストアにすでに存在する証明書から

証明書が証明書マネージャー (certmgr.msc または certlm.msc) にある場合は、ファイルにエクスポートせずに拇印で取得できます。

$cert = Get-ChildItem -Path Cert:\LocalMachine\Root |
    Where-Object { $_.Thumbprint -eq 'AD2C67543E1A2A347B13E4471FA945EC77566FC1' } |
    Select-Object -First 1
$spki = $cert.PublicKey.ExportSubjectPublicKeyInfo()
$hash = [System.Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

ピン留めする証明書の拇印を、 certmgr.msc に表示されている拇印に置き換えます。証明書が別のストアにある場合は、 Cert:\CurrentUser\Root、 \My、または \CA に置き換えます。

ピンの確認

CIで新しく計算されたピンを使用する前に、 curlでサニティチェックを行います。

curl -I --pinnedpubkey 'sha256//<base64>=' https://orchestrator.your-cluster.internal/

• 接続が成功した場合 (または 401 などの無関係な理由で失敗した場合)、ピンは正しいです。
• SSL: public key does not match pinned public keyでcurlが失敗した場合は、再計算します - サーバーが実際に提示する証明書とは異なる証明書をピン留めしている可能性があります。

---

2 つのパラメーターを組み合わせる

--ca-cert と --pinnedpubkey を作成します。接続を成功させるには、有効化されている各チェックに個別に合格する必要があります。

--ca-cert 提供	--pinnedpubkey 提供	承認が必要
×	×	システムの信頼はサーバーを検証します (現在の動作)
○	×	サーバーは、システム信頼 または 指定されたルートに対して検証します
×	○	システムの信頼は、サーバー と リーフの公開鍵がピンと一致することを検証します
○	○	信頼パスは検証 し、 リーフ公開鍵はピンと一致します

ホスト名のチェックは、設定する他のフラグとは無関係に、リーフ証明書のサブジェクト代替名 (SAN が存在しない場合は共通名) に対して常に実行されます。

---

シナリオ

UiPath Automation Suite に接続する

Automation Suite クラスターは、インストール時に独自の自己署名 UiPath AS Root CA 証明書を生成します。クラスターのホスト証明書を検証するには、そのルートをエクスポートし、 --ca-cert経由で渡します。

uipcli solution upload-package "C:\Work\MySolution.1.0.0.zip" `
  -U "https://orchestrator.your-cluster.internal/" `
  -T "DefaultTenant" `
  -A "Default" `
  -I "<your application id>" `
  -S "<your application secret>" `
  --ca-cert "C:\certs\uipath-as-root.crt" `
  --traceLevel Information

システム全体に証明書をインストールする権限のない CI/CD ランナー

CI/CD エージェントは、多くの場合、オペレーティング システムの信頼ストアを変更できない管理者以外のサービス アカウントとして実行されます。--ca-cert 、現在のCLI呼び出しのみに信頼のスコープを設定します。

uipcli package deploy "./output/MyPackage.1.0.0.nupkg" "https://orchestrator.internal/" "DefaultTenant" `
  -A "Default" -I "$env:APP_ID" -S "$env:APP_SECRET" `
  -o "Production" `
  --ca-cert "$env:CI_WORKSPACE/certs/internal-root.pem"

エージェントに必要なのは証明書ファイルの読み取りアクセス権だけで、管理者特権やマシンの状態の変更はありません。

1 つのパイプラインに複数の Orchestrator ターゲット

異なる内部 CA によって署名された複数の Orchestrator インスタンスにパイプラインをデプロイする場合は、各クラスターのルートを一度に指定します。システム信頼ストアは引き続き適用されるため、同じパイプライン内のパブリック Orchestrator は、追加の設定なしで動作し続けます。

uipcli package deploy "./pkg.nupkg" "https://orch-1.internal/" "Tenant1" `
  -A "Org" -I "<id>" -S "<secret>" -o "Folder" `
  --ca-cert "./certs/orch-1.pem,./certs/orch-2.pem"

公的に信頼されたサーバーでの多層防御

オペレーティング システムがすでに信頼している公開 CA によってサーバーが署名されている場合でも、公開キーをピン留めして、システム信頼ストア内の任意の CA の侵害を検出できます。同じホスト名に対して誤って発行された証明書が提示された場合、チェーンの検証に合格したとしても、ピンはそれを拒否します。

uipcli job run MyProcess "https://cloud.uipath.com/" "Tenant" `
  -A "OrgName" -I "<id>" -S "<secret>" -o "Folder" `
  --pinnedpubkey "sha256//<base64 hash>"

プライベート CA の背後にピン留めする

サーバーがプライベート CA を使用する場合は、両方のフラグが必要です。ピンだけではチェーン検証をバイパスしません。

uipcli solution upload-package "MyPackage.1.0.0.zip" `
  -U "https://orchestrator.internal/" -T "Tenant" `
  -A "Org" -I "<id>" -S "<secret>" `
  --ca-cert "./certs/internal-root.pem" `
  --pinnedpubkey "sha256//<base64 hash>"

証明書のローテーション全体でのピンの耐久性

ピンは、証明書ではなく 公開キーを追跡します。サーバーの証明書が更新されても、秘密キーが再利用されても、SubjectPublicKeyInfo の SHA-256 は変わらず、PIN は機能し続けます。サーバーが新しいキー ペアを生成すると、ピンが壊れるので、再計算して更新する必要があります。

特に Automation Suite では、証明書のローテーション動作はクラスターの cert-manager 構成によって異なります。最初のローテーション後に 1 回テストする: 再計算されたピンが古いピンと一致する場合、クラスターがキーを再利用し、ピンが永続的であることを確認しました。異なる場合は、回転ごとにピンを更新することを期待してください。

---

トラブルシューティング

--ca-cert file not found: ./certs/root.pem (resolved to /actual/cwd/certs/root.pem)

現在の作業ディレクトリに対して解決された相対パスであり、その絶対パスにファイルが存在しません。絶対パスを渡すか、CLI が予期されるディレクトリから実行されるようにします。

--ca-cert expects certificates only; '<path>' contains a private key block.

指定したPEMファイルには、証明書に加えて秘密鍵ブロックが含まれています。キーを削除し (トラストアンカーとしての役割はありません)、再試行します。

Could not parse '<path>' as a certificate (PEM/DER/PKCS#7 supported, PFX/PKCS#12 is not).

このファイルは PFX/PKCS#12 である可能性が最も高いです。秘密鍵なしで再エクスポートするか、 openssl pkcs12 -in cert.pfx -nokeys -out cert.pemを使用してPEMに変換します。

--pinnedpubkey must be a SHA-256 hash (32 bytes); got <N> bytes after base64-decoding.

sha256//後の文字列が正確に 32 バイトに base64 デコードされませんでした。上記のレシピのいずれかを使用してピンを再計算します。

内部サーバーに対して設定された --pinnedpubkey でも接続に失敗する

ピンだけではチェーン検証をバイパスしません。チェーンにトラスト アンカーが付くように --ca-cert <root> を追加します。