Atlassian 应用允许我们在自己的应用内使用 SSL,但 Atlassian 支持部门不提供相关配置帮助。因此,Atlassian 不保证为它提供任何支持

  • 如果需要证书转换方面的帮助,请咨询提供证书的提供商。
  • 如果需要相关配置帮助,请在 Atlassian Answers 上提问。

请注意,SHA-1 已经因为已知的缺陷而被淘汰

本页面上的说明介绍了如何通过配置使用 HTTPS 的 Apache Tomcat 来通过 SSL 或 HTTPS 运行 JIRA 应用。此过程只涵盖 JIRA 的常见安装类型。它决不是配置 HTTPS 的权威或全面指南,也可能不适用于您的特定设置。

为什么应该通过 SSL 或 HTTPS 运行 JIRA?通过互联网访问 Web 应用时,用户名和密码始终有可能被计算机和 ISP/公司之间的中间商拦截。启用通过 HTTPS (HTTP over SSL) 的访问并将其作为密码发送页面的要求,这通常是个好主意。但请注意,使用 HTTPS 可能会导致性能降低。

开始之前

在开始之前,请注意以下事项:

  • Atlassian 支持部门会将 SSL 支持提交给负责发放证书的证书颁发机构 (CA)。本页面上提供的 SSL 相关说明仅供参考。
  • 对于使用 Windows 安装程序安装的 JIRA 应用:
    • Windows 安装程序”将安装其自身的 Java 运行时环境 (JRE) Java 平台,用于运行 Tomcat。更新 SSL 证书时,请在此 JRE 安装中进行。
    • 在本文档中,术语 <jira-install-dir> 指的是 JIRA 应用安装目录本身。

如果在反向代理(如 Apache)之后托管 JIRA,请参见使用 SSL 将 JIRA 与 Apache 集成,以了解更多信息。

生成 Java 密钥库

在本部分中,您将创建 Java 密钥库 (JKS),用于保存您的 SSL 证书。SSL 必需获得 SSL 证书才能在 JIRA 中起作用。在 SSL 世界中,证书分为两大类:

证书说明何时使用步骤
自签名证书

是指未经 CA 数字签名的证书,这是一种用来确认由 Web 服务器提供的证书来源的方法。这些证书由证书本身进行签名,因此被称为自签名。

仅用于测试、开发或内部服务器。

1 - 13
CA 签名的证书由证书颁发机构 (CA) 对其身份进行数字签名的证书。这会让浏览器和客户端信任此类证书。生产服务器。1 - 21

由可信任的第三方 CA(证书颁发机构)发放的数字证书提供的验证能够证明您的网站确实代表您的公司,以此来验证您公司的身份。许多 CA 只验证域名就发放证书。其他 CA(如 VeriSign)会验证您的业务是否存在、域名的所有权,以及您申请证书的权利,从而提供更高的身份验证标准。

可以在此处找到 CA 列表。一些最知名的 CA 包括:

我们建议使用 CA 签名的证书。

如果您无法在服务器上安装 Portecle 或更喜欢使用命令行,请参见下面的命令行安装部分。

  1. 在运行 JIRA 的服务器上下载并安装 Portecle 应用。
    (warning) 这是一个第三方应用,因此 Atlassian 不提供支持。
  2. 以管理员身份运行该应用,就会获得相应权限。此外,请确保 <JAVA_HOME> 变量指向的 Java 版本与 JIRA 使用的版本相同。请参见设置 JAVA_HOME,以了解与此相关的更多信息。
    (info) 如果在 Linux/UNIX 服务器上运行,则在连接到服务器时需要转发 X11(以便您可以使用 GUI),如下所示:

    ssh -X user@server
    CODE
  3. 选择 Create a new Keystore 选项:
  4. 选择类型 JKS 并选择“OK”:
  5. 选择 Generate Key Pair 按钮:
  6. 选择 RSA 算法,并为“Key Size”选择“2048”:
  7. 确保 Signature Algorithm 为 "SHA1withRSA",然后按照以下示例编辑证书详情,然后选择“OK”:

    (warning) Common Name 必须与服务器的 URL 相匹配,否则浏览器中将显示错误。
    (info) 如果您想使用 SHA256withRSA,请使用相应的“Signature Algorithm”,请参见:安全工具报告默认的 SSL 密码太弱
  8. 为证书选择一个别名 - 例如 jira。
  9. 输入密钥库的密码(使用的默认密码通常为 changeit)。
  10. 密钥对生成会报告成功,如下所示:
  11. 将密钥库保存在 <JIRA_HOME>/jira.jks 中,确保在步骤 11 中使用相同的密码。此操作可以通过选择 File > Save Keystore 完成。

    如果使用的是自签名证书,请参见使用 JIRA 配置工具配置您的 Web 服务器。否则,请继续。

  12. 我们需要生成一个证书签名请求,以便 CA 签名并确认证书的身份。为此,请右键单击证书并选择 Generate CSR。将其保存在 <JIRA_HOME>/jira.csr 中。
  13. 将 CSR 提交给证书颁发机构签名。他们将提供经过签名的证书(CA 回复)和一组根/中间 CA 证书。
  14. 通过 Import Trusted Certificate 导入根和/或中间 CA 证书,为每个证书重复此步骤。
  15. 在 jira 证书上单击右键并选择 Import CA Reply 来导入经过签名的证书:
  16. 选择 CA 提供的证书,格式应该为 jira.crt。将显示 CA 回复导入成功。
  17. 通过选中 Tools > Keystore Report 对此进行验证。该证书应该显示为根证书的子项。
  18. 保存密钥库并前往下一部分。

使用 JIRA 配置工具配置 Web 服务器

在本部分中,您将通过使用 JIRA 配置工具配置 Web 服务器来完成 JIRA 的 SSL 加密设置。有关 JIRA 配置工具的更多信息,请参见使用 JIRA 配置工具

  1. 运行 JIRA 配置工具,方法如下:
  2. 单击 Web Server 选项卡。
    屏幕截图:JIRA 配置工具 —“Web Server”选项卡
  3. 按照以下所示填写字段:

    字段
    Control Port保留默认值。您可以按照需要更改端口号。请参见更改 JIRA 的 TCP 端口
    Profile配置文件是预设的 Web 服务器配置。您可以从以下四个值中选择:
    • Disabled
    • HTTP only 
    • HTTP & HTTPS (redirect HTTP to HTTPS)
    • HTTPS only

    要通过 HTTPS 运行 JIRA,就必须选择“HTTP & HTTPS”或“HTTPS”。
    如果您希望通过 HTTPS 运行 JIRA,但您有一些用户是通过 HTTP 访问 JIRA,请选择“HTTP & HTTPS”。如果您选择“HTTP & HTTPS”,那么尝试通过 HTTP 访问 JIRA 的用户将被重定向到 HTTPS 地址。

    HTTP port保留默认值 (8080)。您可以按照需要更改端口号。请参见更改 JIRA 的 TCP 端口
    如果您将 Profile 设置为“HTTPS only”,此字段将被禁用。
    HTTPS port保留默认值 (8443)。您可以按照需要更改端口号。请参见更改 JIRA 的 TCP 端口
    Keystore path指定证书密钥库的位置。此设置应当在第 13 步中保存密钥库时进行了选择,应当位于 <JIRA_HOME>/jira.jks
    Keystore password指定密钥库的密码。如果您生成的是自签名证书,则此密码就是在第 13 步中生成证书时为密钥和密钥库指定的密码。
    Keystore alias密钥库中的每个条目都由别名进行标识。我们建议和第 10 步中一样,为此证书使用 jira
  4. 单击 Check Certificate in Key Store 按钮,验证以下内容:
    • 测试是否可以在密钥库中找到证书。
    • 测试密钥库密码是否有效。
    • 测试是否可以使用密钥别名找到密钥。
  5. 单击 Save 按钮保存变更。

高级配置

在同一台主机上运行多个实例

在同一台主机上运行多个实例时,请务必在 <JIRA_INSTALLATION>/conf/server.xml 文件中指定 address 属性,因为默认情况下,连接器会监听所有可用的网络接口,所以指定地址可以防止与同一个默认端口上运行的连接器发生冲突。请参见“Tomcat 连接器”文档,了解 HTTP 连接器 Apache Tomcat 文档中有关设置地址属性的更多信息。

命令行安装

步骤 1.创建密钥库

  1. 生成 Java 密钥库:

    <JAVA_HOME>/keytool -genkey -alias jira -keyalg RSA -keystore <JIRA_HOME>/jira.jks
    BASH

    (info)请输入服务器 URL(不包含“https://”),而不是姓名。(例如:jira.atlassian.com)。

  2. 输入密码。
  3. 使用步骤 2 中的密码,创建用于签名的 CSR:
  4. 将 CSR 提交给 CA 进行签名。他们将提供一个经过签名的证书和一个根和/或中间 CA。
    (warning) 如果证书不用签名,请跳至步骤 7。
  5. 导入根和/或中间 CA:

    <JAVA_HOME>/keytool -import -alias rootCA -keystore <JIRA_HOME>/jira.jks -trustcacerts -file root.crt
    BASH
  6. 导入经过签名的证书(由 CA 提供):

    <JAVA_HOME>/keytool -import -alias jira -keystore <JIRA_HOME>/jira.jks -file jira.crt
    BASH
  7. 验证该证书在密钥库中存在:

    <JAVA_HOME>/keytool -list -alias jira -keystore <JIRA_HOME>/jira.jks
    BASH

    这一定是一个 PrivateKeyEntry,如果不是,那么证书设置没有成功完成。例如:

    jira, Jan 1, 1970, PrivateKeyEntry,Certificate fingerprint (MD5):73:68:CF:90:A8:1D:90:5B:CE:2A:2F:29:21:C6:B8:25

步骤 2. 使用密钥库更新 Tomcat

  1. 先创建 <JIRA_INSTALL>/conf/server.xml 的备份,然后再进行编辑。
  2. 编辑 HTTPS 连接器,以便其拥有指向密钥库的参数:

    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"              maxHttpHeaderSize="8192" SSLEnabled="true"              maxThreads="150" minSpareThreads="25"              enableLookups="false" disableUploadTimeout="true"              acceptCount="100" scheme="https" secure="true"              sslEnabledProtocol="TLSv1.2"              clientAuth="false" sslProtocol="TLSv1.2" useBodyEncodingForURI="true"              keyAlias="jira" keystoreFile="<JIRA_HOME>/jira.jks" keystorePass="changeit" keystoreType="JKS"/>
    CODE

    (info) 确保用正确的路径来代替 <JIRA_HOME>,并根据需要更改端口。

    如果组织不支持最新版本的 TLS,您可以退回到版本 1.0。将:

    sslEnabledProtocol="TLSv1.2"
    CODE

    更改为:

    sslEnabledProtocol="TLS"
    CODE
  3. 编辑 HTTP 连接器,将其重定向到 HTTPS 连接器:

    <Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" port="8080" protocol="HTTP/1.1" redirectPort="<PORT_FROM_STEP_1>" useBodyEncodingForURI="true"/>
    CODE

    (info) 请务必将 <PORT_FROM_STEP_1> 变更为适当的值。在本示例中,该值为 8443。

  4. 保存对 server.xml 所作的变更。
  5. 如果打算重定向到 HTTPS(推荐使用),请编辑 <JIRA_INSTALL>/WEB-INF/web.xml 文件,在文件的末尾,结束标记 </web-app> 的前面添加以下部分。在本示例中,除附件以外的所有 URL 都会从 HTTP 重定向到 HTTPS。

    <security-constraint>	<web-resource-collection>		<web-resource-name>all-except-attachments</web-resource-name>		<url-pattern>*.jsp</url-pattern>		<url-pattern>*.jspa</url-pattern>		<url-pattern>/browse/*</url-pattern>		<url-pattern>/issues/*</url-pattern>	</web-resource-collection>	<user-data-constraint>		<transport-guarantee>CONFIDENTIAL</transport-guarantee>	</user-data-constraint></security-constraint>
    CODE
  6. 保存变更后请重新启动 JIRA。

您还可以通过在 JIRA 配置工具中选择“HTTP & HTTPS”配置文件,将用户从 HTTP URL 重定向到 HTTPS URL。这会将所有 HTTP URL 重定向到 HTTPS URL。

如果您只想将特定页面重定向到 HTTPS,则需要手动执行此操作。为此,请在 JIRA 配置工具中选择“HTTPS only”配置文件并保存配置,然后在您的 Web 服务器上创建一个 htaccess 文件,这样即可将 HTTP URL 手动重定向到相应 HTTPS URL。

故障排除

如果您正在使用由 Portecle 创建的自签名密钥(如上所述),下面是一些故障排除的提示。

当您在浏览器中输入“https://localhost:<port number>”时,如果收到了一条消息,例如“无法建立与服务器 localhost:8443 的连接”,请在您的 logs/catalina.out 日志文件中寻找错误消息。下面是一些可能发生的错误及相关说明。

  • SSL + Apache + IE 问题:一些人在使用 IE 通过 SSL 上传附件时报告了错误。这是由于 IE 缺陷,可以通过以下设置在 Apache 中修复:

    BrowserMatch ".MSIE." \nokeepalive ssl-unclean-shutdown \downgrade-1.0 force-response-1.0
    CODE

    Google 还有很多类似的问题。

  • 找不到密钥库:

    java.io.FileNotFoundException: /home/user/.keystore (No such file or directory)

    这表明 Tomcat 找不到密钥库。Keytool 实用工具在当前用户的主目录中以文件的形式创建了密钥库,文件名为 .keystore。对于 Unix/Linux,主目录可能是 /home/<username>。对于 Windows,则可能是 C:\Documents And Settings\<UserName>

    请确保您运行 JIRA 时使用的用户身份与创建该密钥库的用户身份相同。如果不是这种情况,或者如果您在 Windows 上将 JIRA 作为服务运行,则需要在 conf/server.xml 中指定密钥库文件所在的位置。将以下属性添加到已取消注释的连接器标签中:

    keystoreFile="<密钥库文件的位置>"

    如果您在 server.xml 中将 keystoreFile 属性添加到 http 连接器而不是 https 连接器中,这种情况也会发生 (“Cannot find /root/.keystore”)。

  • 证书回复和密钥库中的证书完全相同:

    keytool error: java.lang.Exception: Certificate reply and certificate in keystore are identical

    如果由于试图在现有的密钥库中重新创建证书,您拥有了相同的名称或指纹,则会发生这种错误。如果您需要重新创建或更新证书,可以删除现有的密钥库并创建一个全新的密钥库。在这种情况下,创建新的密钥库并添加相关证书可以解决这个问题。本文档中它的默认路径为 $JAVA_HOME/jre/lib/security/cacerts

  • 密码错误

    java.io.IOException: Keystore was tampered with, or password was incorrect

    您使用了与“changeit”不同的密码。您必须将“changeit”同时用作密钥库的密码和 Tomcat 的密钥密码,或者,如果您想使用其他密码,则必须使用连接器标签的 keystorePass 属性进行指定(如上所述)。

  • 密码不符:

    java.io.IOException:Cannot recover key

    您为密钥库密码和 Tomcat 的密钥密码指定了不同的值。这两个密码必须相同。

  • 证书错误:

    javax.net.ssl.SSLException:No available certificate corresponds to the SSL cipher suites which are enabled.

    如果 Keystore 的证书不止一个,Tomcat 将使用返回的第一个证书,除非已在 conf/server.xml 的 SSL 连接器中进行了指定。

    keyAlias 属性及相关别名添加到已取消注释的连接器标签中,例如:

     <Connector port="8443" maxHttpHeaderSize="8192"maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true"acceptCount="100" scheme="https" secure="true"clientAuth="false" sslProtocol="TLS"keystoreFile="/opt/local/.keystore"keystorePass="removed"keyAlias="tomcat"/>
  • 使用 Apache Portable Runtime:

    APR 使用了其他的 SSL 引擎,您会在日志中看到类似以下错误的异常

     SEVERE:Failed to initialize connector [Connector[HTTP/1.1-8443]]LifecycleException:Protocol handler initialization failed:java.lang.Exception:No Certificate file specified or invalid file format

    异常发生的原因是 APR 连接器使用了 OpenSSL,无法以相同的方式使用密钥库。您可以通过以下两种方式之一进行改正:


    • 使用 Http11NioProtocol 处理 SSL 连接 — 编辑 server.xml,使您刚刚取消注释的 SSL 连接器标签指定 Http11NioProtocol 而不是 APR 协议

      <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"  maxHttpHeaderSize="8192" SSLEnabled="true" keystoreFile="${user.home}/.keystore"  maxThreads="150" enableLookups="false" disableUploadTimeout="true"  acceptCount="100" scheme="https" secure="true"  clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"/>
    • 将连接器配置为使用 APR 协议 — 只有在您拥有 PEM 编码的证书和私有密钥的情况下才能执行此操作。如果您使用的是 OpenSSL 来生成密钥,那么您将拥有这些 PEM 编码的文件 - 在所有其他情况下,请联系您的证书提供商寻求帮助。

      <Connector  port="8443" maxThreads="200"  scheme="https" secure="true" SSLEnabled="true"  SSLCertificateFile="${user.home}/certificate.pem"  SSLCertificateKeyFile="${user.home}/key.pem"  clientAuth="optional" SSLProtocol="TLSv1"/>
  • 启用客户端身份验证:要在 Tomcat 中启用客户端身份验证,请确保 Tomcat 的 server.xml 文件的 Connector 元素中 clientAuth 属性为 true

    <Connector	...	clientAuth="true"	.../>

    有关 Connector 元素参数的更多信息,请参阅 SSL 配置方法 Tomcat 8 文档。