使用自我簽署憑證執行代理程式

Azure DevOps Server 2022 - Azure DevOps Server 2019

本主題說明如何使用自我簽署憑證來執行自我裝載代理程式。

注意

本文適用於代理程式 2.x 版和更新版本。

使用 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

此錯誤可能表示您在 TFS 伺服器上所使用的伺服器證書不受組建電腦信任。 請務必將自我簽署 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

注意

在 Linux 和 macOS 上使用此旗標有限制
Linux 或 macOS 電腦上的 libcurl 連結庫需要使用 OpenSSL 建置， 更詳細數據

Git 取得來源因 SSL 憑證問題而失敗（僅限 Windows 代理程式）

我們會將命令行 Git 隨附為 Windows 代理程式的一部分。 我們會針對所有 Git 相關作業使用此 Git 複本。 當您有內部部署 TFS 伺服器的自我簽署 SSL 憑證時，請務必設定我們隨附的 Git 以允許該自我簽署 SSL 憑證。 有 2 種方法可以解決問題。

1. 藉由代理程式以使用者身分執行，在全域層級中設定下列 Git 組態。

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

   注意

   在 Windows 上設定系統層級 Git 組態並不可靠。 系統會使用我們封裝的 Git 複本來儲存系統 .gitconfig 檔案，每當代理程序升級至新版本時，就會加以取代。

2. 在代理程式設定期間，讓 git 在設定期間使用 SChannel 2.129.0 或更高版本的代理程序傳遞--gituseschannel

   ./config.cmd --gituseschannel
   

   注意

   Git SChannel 對自我簽署憑證的需求有所限制。 IIS 或 PowerShell 命令所產生的自我唱證可能無法搭配 SChannel 使用。

使用 SSL 用戶端憑證

IIS 具有 SSL 設定，需要 Azure DevOps Server 或 TFS 的所有連入要求，除了一般認證之外，還必須提供用戶端憑證。

啟用 IIS SSL 設定時，您必須使用 2.125.0 或更新版本代理程式，並遵循這些額外的步驟，以針對您的 Azure DevOps 或 TFS 伺服器設定組建計算機。

• 準備所有必要的憑證資訊

  • CA 憑證 .pem 的格式 （這應該包含 CA 憑證的公鑰和簽章，您需要將根 CA 憑證和所有中繼 CA 憑證放入一個 .pem 檔案中）
  • 格式的 .pem 用戶端憑證 （這應該包含用戶端憑證的公鑰和簽章）
  • 格式的 .pem 用戶端憑證私鑰 （這應該只包含用戶端憑證的私鑰）
  • 格式的 .pfx 用戶端憑證封存套件 （這應該包含用戶端憑證的簽章、公鑰和私鑰）
  • 使用 SAME 密碼來保護用戶端憑證私鑰和用戶端憑證封存套件，因為它們都有用戶端憑證的私鑰

• 將 CA 憑證安裝到電腦證書存儲

  • Linux：OpenSSL 證書存儲
  • macOS：系統或使用者密鑰鏈
  • Windows：Windows 證書存儲

• 傳遞 --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
  

深入瞭解 代理程式客戶端憑證支援。