Atlassian 应用允许我们在自己的应用内使用 SSL,但 Atlassian 支持部门不提供相关配置帮助。因此,Atlassian 不保证为它提供任何支持。
- 如果需要证书转换方面的帮助,请咨询提供证书的提供商。
- 如果需要相关配置帮助,请在 Atlassian Answers 上提问。
请注意,SHA-1 已经因为已知的缺陷而被淘汰。
开始之前
在开始之前,请注意以下事项:
- 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 或更喜欢使用命令行,请参见下面的命令行安装部分。
- 在运行 JIRA 的服务器上下载并安装 Portecle 应用。
这是一个第三方应用,因此 Atlassian 不提供支持。 以管理员身份运行该应用,就会获得相应权限。此外,请确保
<JAVA_HOME>
变量指向的 Java 版本与 JIRA 使用的版本相同。请参见设置 JAVA_HOME,以了解与此相关的更多信息。
如果在 Linux/UNIX 服务器上运行,则在连接到服务器时需要转发 X11(以便您可以使用 GUI),如下所示:ssh -X user@server
- 选择 Create a new Keystore 选项:
- 选择类型 JKS 并选择“OK”:
- 选择 Generate Key Pair 按钮:
- 选择 RSA 算法,并为“Key Size”选择“2048”:
- 确保 Signature Algorithm 为
"SHA1withRSA"
,然后按照以下示例编辑证书详情,然后选择“OK”:
Common Name 必须与服务器的 URL 相匹配,否则浏览器中将显示错误。
如果您想使用 SHA256withRSA,请使用相应的“Signature Algorithm”,请参见:安全工具报告默认的 SSL 密码太弱。 - 为证书选择一个别名 - 例如 jira。
- 输入密钥库的密码(使用的默认密码通常为
changeit
)。 - 密钥对生成会报告成功,如下所示:
将密钥库保存在
<JIRA_HOME>/jira.jks
中,确保在步骤 11 中使用相同的密码。此操作可以通过选择 File > Save Keystore 完成。如果使用的是自签名证书,请参见使用 JIRA 配置工具配置您的 Web 服务器。否则,请继续。
- 我们需要生成一个证书签名请求,以便 CA 签名并确认证书的身份。为此,请右键单击证书并选择 Generate CSR。将其保存在 <JIRA_HOME>/jira.csr 中。
- 将 CSR 提交给证书颁发机构签名。他们将提供经过签名的证书(CA 回复)和一组根/中间 CA 证书。
- 通过 Import Trusted Certificate 导入根和/或中间 CA 证书,为每个证书重复此步骤。
- 在
jira
证书上单击右键并选择 Import CA Reply 来导入经过签名的证书: - 选择 CA 提供的证书,格式应该为
jira.crt
。将显示 CA 回复导入成功。 - 通过选中 Tools > Keystore Report 对此进行验证。该证书应该显示为根证书的子项。
- 保存密钥库并前往下一部分。
使用 JIRA 配置工具配置 Web 服务器
在本部分中,您将通过使用 JIRA 配置工具配置 Web 服务器来完成 JIRA 的 SSL 加密设置。有关 JIRA 配置工具的更多信息,请参见使用 JIRA 配置工具。
- 运行 JIRA 配置工具,方法如下:
- Windows:打开命令提示符,并在 JIRA 安装目录的
bin
子目录中运行config.bat
。 - Linux/Unix:打开控制台,并在 JIRA 安装目录的
bin
子目录中执行config.sh
。
这可能会失败,并产生错误,如我们的“因 No X11 DISPLAY 变量设置错误而无法启动 JIRA 应用配置工具”知识库文章中所述。请参见该文章,了解解决方法。
- Windows:打开命令提示符,并在 JIRA 安装目录的
- 单击 Web Server 选项卡。
屏幕截图:JIRA 配置工具 —“Web Server”选项卡 按照以下所示填写字段:
字段 值 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
。- Disabled
- 单击 Check Certificate in Key Store 按钮,验证以下内容:
- 测试是否可以在密钥库中找到证书。
- 测试密钥库密码是否有效。
- 测试是否可以使用密钥别名找到密钥。
- 单击 Save 按钮保存变更。
高级配置
在同一台主机上运行多个实例
在同一台主机上运行多个实例时,请务必在 <JIRA_INSTALLATION>/conf/server.xml
文件中指定 address 属性,因为默认情况下,连接器会监听所有可用的网络接口,所以指定地址可以防止与同一个默认端口上运行的连接器发生冲突。请参见“Tomcat 连接器”文档,了解 HTTP 连接器 Apache Tomcat 文档中有关设置地址属性的更多信息。
命令行安装
步骤 1.创建密钥库
生成 Java 密钥库:
<JAVA_HOME>/keytool -genkey -alias jira -keyalg RSA -keystore <JIRA_HOME>/jira.jks
请输入服务器 URL(不包含“https://”),而不是姓名。(例如:jira.atlassian.com)。
- 输入密码。
- 使用步骤 2 中的密码,创建用于签名的 CSR:
- 将 CSR 提交给 CA 进行签名。他们将提供一个经过签名的证书和一个根和/或中间 CA。
如果证书不用签名,请跳至步骤 7。 导入根和/或中间 CA:
<JAVA_HOME>/keytool -import -alias rootCA -keystore <JIRA_HOME>/jira.jks -trustcacerts -file root.crt
导入经过签名的证书(由 CA 提供):
<JAVA_HOME>/keytool -import -alias jira -keystore <JIRA_HOME>/jira.jks -file jira.crt
验证该证书在密钥库中存在:
<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
- 先创建
<JIRA_INSTALL>/conf/server.xml
的备份,然后再进行编辑。 编辑 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"
编辑 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。- 保存对
server.xml
所作的变更。 如果打算重定向到 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>
- 保存变更后请重新启动 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
日志文件中寻找错误消息。下面是一些可能发生的错误及相关说明。