使用自签名证书运行代理

  • 项目

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 服务器证书安装到操作系统证书存储中。

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 证书。 有两种方法可以解决此问题。

  1. 通过以用户身份运行的代理在全局级别设置以下 git 配置。

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

    注意

    设置系统级 Git 配置在 Windows 上并不可靠。 系统 .gitconfig 文件与我们打包的 Git 副本一起存储，每当代理升级到新版本时，就会替换该文件。

  2. 在使用 2.129.0 或更高版本的代理进行配置时，启用 git 以使用 SChannel 在代理配置期间通过 --gituseschannel

    ./config.cmd --gituseschannel

    注意

    Git SChannel 对自签名证书的要求更严格。 由 IIS 或 PowerShell 命令生成的自加密证书可能无法使用 SChannel。

使用 SSL 客户端证书

IIS 有 SSL 设置，要求对 Azure DevOps Server 或 TFS 的所有传入请求除常规凭证外，还必须出示客户端证书。

在启用 IIS SSL 设置后，需要使用 2.125.0 或更高版本的代理，并遵循这些额外步骤，以便针对 Azure DevOps 或 TFS 服务器配置构建计算机。

  • 准备所有必需的证书信息

    • .pem 格式的 CA 证书（其中应包含 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

详细了解代理客户端证书支持。