自己署名証明書を使用してエージェントを実行する

Azure DevOps Server |Azure DevOps Server 2022

この記事では、Azure Pipelines と Azure DevOps Server の自己署名証明書を使用してセルフホステッド エージェントを実行する方法について説明します。

SSL サーバー証明書を操作する

Enter server URL > https://corp.tfs.com/tfs
Enter authentication type (press enter for Integrated) >
Connecting to server ...
An error occurred while sending the request.

エージェント診断ログには、次の情報が表示されます。

[2017-11-06 20:55:33Z ERR  AgentServer] System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Net.Http.WinHttpException: A security error occurred

上記のセキュリティ エラーは、ビルド マシンが、Azure Devops Server ホスト コンピューターで使用したサーバー証明書を信頼していないことを示している可能性があります。 自己署名 SSL サーバー証明書を OS 証明書ストアにインストールしていることを確認します。

Windows: Windows certificate store
Linux: OpenSSL certificate store
macOS: OpenSSL certificate store for agent version 2.124.0 or below
       Keychain for agent version 2.125.0 or above

いくつかのコマンドを実行すると、証明書が正しくインストールされているかどうかを簡単に確認できます。 SSL ハンドシェイクが正しく完了している限り (要求に対して 401 を取得した場合でも)、インストールは成功しました。

Windows: PowerShell Invoke-WebRequest -Uri https://corp.tfs.com/tfs -UseDefaultCredentials 
Linux: curl -v https://corp.tfs.com/tfs 
macOS: curl -v https://corp.tfs.com/tfs (agent version 2.124.0 or below, curl needs to be built for OpenSSL)
       curl -v https://corp.tfs.com/tfs (agent version 2.125.0 or above, curl needs to be built for Secure Transport)

さまざまな理由 (適切なアクセス許可がない、カスタマイズされた Linux マシン上にいるなど) のために証明書をコンピューターの証明書ストアに正常にインストールできない場合は、別のオプションがあります。 エージェント バージョン 2.125.0 以降では、SSL サーバー証明書検証エラーを無視できます。

エージェントの構成中に --sslskipcertvalidation を渡します。

./config.cmd/sh --sslskipcertvalidation

問題: Git get sources コマンドが SSL 証明書で失敗する (Windows エージェントのみ)

Windows エージェントの一部としてコマンドライン Git を出荷し、Git 関連のすべての操作にこの Git のコピーを使用します。 オンプレミスの Azure DevOps Server マシン用の自己署名 SSL 証明書がある場合は、自己署名 SSL 証明書を許可するように配布済みの Git を構成します。

この問題を解決するには、次の 2 つの方法があります。

• 次の git config を、エージェントのユーザーとしての実行によってグローバル レベルで設定します。

  git config --global http."https://tfs.com/".sslCAInfo certificate.pem
  

  注

  システム レベルの git config の設定は、Windows では信頼できません。 システム .gitconfig ファイルは、パッケージ化した Git のコピーと共に格納されます。 パッケージ化された Git は、エージェントが新しいバージョンにアップグレードされるたびに置き換えられます。

• 2.129.0 以降のバージョン のエージェントを使用している場合に、構成中に git で SChannel を使用できるようにします。 エージェントの構成中に --gituseschannel を渡します。

  ./config.cmd --gituseschannel
  

  注

  Git SChannel には、自己署名証明書に対するより制限の厳しい要件があります。 インターネット インフォメーション サービス (IIS) または PowerShell コマンドによって生成される自己署名証明書は、 SChannelと互換性がない可能性があります。

SSL クライアント証明書を操作する

IIS には SSL 設定があり、Azure DevOps Server へのすべての受信要求でクライアント証明書と通常の資格情報を提示する必要があります。

その IIS SSL 設定が有効になっている場合は、バージョン 2.125.0 以降を使用し、Azure DevOps Server に対してビルド マシンを構成するには、次の追加の手順を実行する必要があります。

1. 必要なすべての証明書情報を準備します。

   • .pem形式の証明機関 (CA) 証明書: このファイルには、CA 証明書の公開キーと署名が含まれている必要があります。 ルート CA 証明書とすべての中間 CA 証明書を 1 つの .pem ファイルに配置する必要があります。
   • .pem形式のクライアント証明書: このファイルには、クライアント証明書の公開キーと署名が含まれている必要があります。
   • .pem形式のクライアント証明書の秘密キー: このファイルには、クライアント証明書の秘密キーのみを含める必要があります。
   • .pfx形式のクライアント証明書アーカイブ パッケージ: このファイルには、クライアント証明書の署名、公開キー、秘密キーが含まれている必要があります。
   • パスワード: クライアント証明書の秘密キーとクライアント証明書アーカイブ パッケージの両方にクライアント証明書の秘密キーがあるため、同じパスワードを使用して保護します。

2. コンピューター証明書ストアに CA 証明書をインストールします。

   • Linux: OpenSSL 証明書ストア
   • macOS: システムキーチェーンまたはユーザーキーチェーン
   • Windows: Windows 証明書ストア

3. --sslcacert、--sslclientcert、--sslclientcertkeyを渡します。 --sslclientcertarchive と --sslclientcertpassword はエージェントの構成時に同時に使用されます。

   .\config.cmd/sh --sslcacert ca.pem --sslclientcert clientcert.pem --sslclientcertkey clientcert-key-pass.pem --sslclientcertarchive clientcert-archive.pfx --sslclientcertpassword "mypassword"
   

   クライアント証明書の秘密キーのパスワードは、各プラットフォームに安全に保存されます。

   Linux: Encrypted with a symmetric key based on the machine ID
   macOS: macOS Keychain
   Windows: Windows Credential Store
   

ルート証明機関の信頼を確認する

ビルド エージェントは、Mozilla の信頼されたルート証明書から派生した独自の証明書ストアに依存する Node.jsを使用します。 Node.js 証明機関ストアは、セキュリティで保護された通信に使用するすべてのルート証明書を信頼する必要があります。 それ以外の場合は、Azure DevOps Server コンピューターで証明書を更新した後に、次のエラーが発生する可能性があります。

• "ローカル発行者証明書を取得できません"
• "SELF_SIGNED_CERT_IN_CHAIN"
• "最初の証明書を確認できません"

tls.rootCertificates配列を使用して、TLS/SSL 接続の検証に使用する信頼されたルート CA を確認できます。

# Sample script to extract Node.js root certificates using Node.js.  
node -e ' 
const tls = require("tls"); 
console.log(tls.rootCertificates.join("\n")); 
' > "$ROOT_CERTS_FILE" 

Node v7.3.0 で導入された NODE_EXTRA_CA_CERTS 環境変数を使用すると、ノードが信頼する 1 つ以上の CA 証明書を含むファイルを指定できます (既定のバンドルに加えて)。 NODE_EXTRA_CA_CERTS は信頼ストアに追加されます。

1. サーバーまたは CA で、ルート証明書 (および必要に応じて中間証明書) を PEM でエンコードされたファイルとしてエクスポートします。 この形式は、 -----BEGIN CERTIFICATE----- と Base64 データを含むテキスト ファイルです。 DER ではなく、Base64 でエンコードされた PEM を使用していることを確認します。 (Windows では、.cerファイルはどちらかになります。混乱を避けるために.pem に名前を変更できます。ファイルは実際には任意の拡張子を持つことができますが、.pem または .crt は標準です)。

   複数の内部 CA (チェーン) がある場合は、それらを 1 つのファイルに連結できます。 ノードは、そのファイル内のすべての証明書を読み取ります。

2. ビルド エージェントで PEM を使用できるようにするには、それを既知のパス ( C:\certs\CorpRootCA.pem or /etc/ssl/certs/CorpRootCA.pem など) に配置します。

3. PEM ファイルを指す OS 環境変数 ( NODE_EXTRA_CA_CERTS) を設定します。 たとえば、Windows で PowerShell を使用できます。

[Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:\certs\CorpRootCA.pem", "Machine")

関連コンテンツ

エージェント クライアント証明書のサポートについて詳しくは、こちらをご覧ください。