通过 SSL 或 HTTPS 运行 JIRA 应用

开始之前

在开始之前，请注意以下事项：

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

生成 Java 密钥库

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

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

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

• Verisign
• Thawte
• CAcert（相对较新的 CA，提供免费的 CA 证书）

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

1. 在运行 JIRA 的服务器上下载并安装 Portecle 应用。
    这是一个第三方应用，因此 Atlassian 不提供支持。

2. 以管理员身份运行该应用，就会获得相应权限。此外，请确保 <JAVA_HOME> 变量指向的 Java 版本与 JIRA 使用的版本相同。请参见设置 JAVA_HOME，以了解与此相关的更多信息。
    如果在 Linux/UNIX 服务器上运行，则在连接到服务器时需要转发 X11（以便您可以使用 GUI），如下所示：

   ssh -X user@server

3. 选择 Create a new Keystore 选项：
   
4. 选择类型 JKS 并选择“OK”：
   
5. 选择 Generate Key Pair 按钮：
   
6. 选择 RSA 算法，并为“Key Size”选择“2048”：
   
7. 确保 Signature Algorithm 为 "SHA1withRSA"，然后按照以下示例编辑证书详情，然后选择“OK”：
   
    Common Name 必须与服务器的 URL 相匹配，否则浏览器中将显示错误。
    如果您想使用 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 配置工具，方法如下：
   
   • Windows：打开命令提示符，并在 JIRA 安装目录的 bin 子目录中运行 config.bat。
   • Linux/Unix：打开控制台，并在 JIRA 安装目录的 bin 子目录中执行 config.sh。
      这可能会失败，并产生错误，如我们的“因 No X11 DISPLAY 变量设置错误而无法启动 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

   请输入服务器 URL（不包含“https://”），而不是姓名。（例如：jira.atlassian.com）。

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

5. 导入根和/或中间 CA：

   <JAVA_HOME>/keytool -import -alias rootCA -keystore <JIRA_HOME>/jira.jks -trustcacerts -file root.crt

6. 导入经过签名的证书（由 CA 提供）：

   <JAVA_HOME>/keytool -import -alias jira -keystore <JIRA_HOME>/jira.jks -file jira.crt

7. 验证该证书在密钥库中存在：

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

   这一定是一个 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"/>

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

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

   sslEnabledProtocol="TLSv1.2"

   更改为：

   sslEnabledProtocol="TLS"

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"/>

    请务必将 <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>

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 日志文件中寻找错误消息。下面是一些可能发生的错误及相关说明。