TeamCity On-Premises 2024.03 Help

使用 HTTPS 访问 TeamCity 服务器

此文件描述了如何配置 Java 应用程序,以使用 HTTPS 与服务器进行通信。
如果您需要将 TeamCity 服务器连接到使用自签名证书的服务背后(例如,Git)或者如果您需要使用自签名证书将 TeamCity 代理连接到 TeamCity 服务器,请使用可信任证书配置

我们假定您已在您的 TeamCity 网络服务器中配置了 HTTPS。 您可以使用TeamCity HTTPS 设置来实现,或者设置像 Nginx 或 Apache 这样的反向代理服务器,为仅支持 HTTP 的 TeamCity 服务器的 Tomcat 端口提供 HTTPS 访问。 在设置中,确保反向代理按照 在代理服务器后设置 TeamCity部分的正确配置。

通过 HTTPS 访问服务器

如果您的证书有效(即它是由 Verisign 等知名的证书授权机构签署的),那么 TeamCity 客户端应该可以在无需任何额外配置的情况下使用 HTTPS。 您只需使用指向 TeamCity 服务器的 https:// 链接,而不是 http://

如果您的证书无效(即:自签名证书):(即,没有经过知名证书颁发机构签名的证书,可能会导致“PKIX路径构建失败:sun.security.provider.certpath.SunCertPathBuilderException:无法找到到请求目标的有效证书路径”错误消息)

  • 要启用来自 TeamCity Visual Studio Add-in 的 HTTPS 连接,将您的 Internet Explorer 指向使用 https:// URL 的 TeamCity 服务器,并将服务器证书导入到浏览器中。 之后,Visual Studio 插件应能通过 HTTPS 连接。

  • 要启用来自 Java 客户端(如 TeamCity 代理、IntelliJ IDEA 等)的 HTTPS 连接,请查看 下面的部分,以配置连接应用程序所使用的 JVM 安装。

配置 JVM

配置客户端 JVM 以信任服务器证书

如果您的证书是有效的(即它是由像 Verisign 这样的知名证书颁发机构发行和签署的),那么 Java 客户端应该可以在没有任何额外配置的情况下使用 HTTPS。 要使用 Let's Encrypt 发行的证书,请务必将客户端使用的 JVM 升级到最新版本。

如果您的证书无效(是自签名的):

为了使 Java 客户端能够启用 HTTPS 连接,您需要将服务器证书(或者您的组织签署的服务器证书)安装到 JVM 作为受信任的证书。 这些是通用的 Java 应用程序步骤(并非特指 TeamCity):

  • 将服务器证书的 CA 根证书保存到一个以 支持的格式 (以下简称 <cert file>)的文件中。 这可以通过在浏览器中检查证书数据并将其以 Base64 编码的 X.509 证书形式导出来完成。

  • 定位进程使用的 JRE。 获取正确的 Java 安装路径的最佳方式是查看正在运行的进程的命令行。 * 如果已安装 JDK(如 IntelliJ IDEA),则 < JRE 安装路径> 应为 < 使用的 JDK 路径>/jre

  • 对于在Windows下安装的 TeamCity 代理或服务器,<JRE安装路径>的默认位置是 <TeamCity安装路径>/jre

  • 使用JVM的 keytool 工具将服务器证书导入到默认的JRE安装密钥库中:

keytool -importcert -file <cert file> -keystore <path to JRE installation>/lib/security/cacerts

默认情况下,Java keystore 受密码 " changeit " 的保护,您需要在提示符下输入。

  • 重启 JVM

配置 JVM 用于客户端证书认证

如果您在 TeamCity 服务器前实施了基于客户端证书的自定义身份验证,您将需要确保 JVM 客户端能够正确地使用其证书进行身份验证。

导入客户端证书

如果您需要使用客户端证书通过 https 访问服务器(例如从 IntelliJ IDEA 或构建代理),您将需要将证书添加到 Java keystore,并将 keystore 提供给被连接过程使用的 JVM。

1. 如果您的证书在一个 p12 文件中,您可以使用以下命令将其转换为 Java keystore。 请确保您使用来自 JDK 1.6-1.8 的 keytool :早期版本可能无法理解 p12 格式。

keytool -importkeystore -srckeystore <path to your .p12 certificate> -srcstoretype PKCS12 -srcstorepass <password of your p12 certificate> -destkeystore <path to keystore file>  -deststorepass <keystore password> -destkeypass <keystore password> -srcalias 1

这些命令从您的 .p12 文件中提取带有别名 "1" 的证书,并将其添加到 Java keystore 中。您应该知道 < 您的 .p12 证书的路径 > 和 < 您的 p12 证书的密码 > ,并且您可以为 < keystore 文件的路径 > 和 < keystore 密码 > 提供新的值。

在这里, keypass 应等于 storepass ,因为只有 storepass 被提供给 JVM,如果 keypass 不同,可能会出现以下错误:"java.security.NoSuchAlgorithmException: Error constructing implementation (algorithm: Default, provider: SunJSSE, class: com.sun.net.ssl.internal.ssl.DefaultSSLContextImpl)"。

导入根证书以组织信任链

如果您的证书未由受信任的机构签署,您还需要将您的证书链的根证书添加到受信任的密钥库,并向 JVM 提供这个受信任的密钥库。

2. 您应首先从您的证书中提取根证书。 如果您已经安装了证书,您可以从网页浏览器进行此操作,或者您可以使用 OpenSSL 工具,使用以下命令进行操作:

openssl.exe pkcs12 -in <path to your .p12 certificate> -out <path to your certificate in .pem format>

您应该知道 <path to your .p12 certificate> 及其密码(在提示时输入)。 当提示时,您应该为 <您的 .pem 格式证书的路径> 和 pem 密语指定新的值。

3. 然后,您应该从 pem 文件(它具有文本格式)中提取根证书(根证书应具有相同的发行者和主题字段)到单独的文件中。 该文件应如下所示:

-----BEGIN CERTIFICATE----- MIIGUjCCBDqgAwIBAgIEAKmKxzANBgkqhkiG9w0BAQQFADBwMRUwEwYDVQQDEwxK ... -----END CERTIFICATE-----

我们假设它的名称是 <根证书的路径>。

4. 现在使用以下命令将根证书导入到受信任的密钥库:

keytool -importcert -trustcacerts -file <path to root certificate> -keystore <path to trust keystore file> -storepass <trust keystore password>

在这里,您可以为 <trust keystore path> 和 <trust keystore password> 使用新的值(或使用现有的信任密钥库)。

开始连接应用程序 JVM

现在您需要在运行应用程序时向 JVM 传递以下参数:

-Djavax.net.ssl.keyStore=<path to keystore file> -Djavax.net.ssl.keyStorePassword=<keystore password> -Djavax.net.ssl.trustStore=<path to trust keystore file> -Djavax.net.ssl.trustStorePassword=<trust keystore password>

对于 IntelliJ IDEA,您可以将这些行添加到 bin\idea.exe.vmoptions 文件中(一行一项)。 对于 TeamCity 构建代理,参见 代理启动属性

分析证书问题中的有用工具

最后修改日期: 16日 7月 2024年