共用方式為

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

  • 發行項

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 組態並不可靠。 系統 .gitconfig 檔案會與我們封裝的 Git 複本一同儲存，當代理程式升級到新版本時，這些檔案會被替換。

  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

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