JIRA を SSL または HTTPS 上で実行する

When web applications are being accessed across the internet, there is always the possibility of usernames and passwords being intercepted by intermediaries between your computer and the ISP/company. It is often a good idea to enable access via HTTPS (HTTP over SSL) and make this a requirement for pages where passwords are sent. Note, however, that using HTTPS may result in slower performance. In some cases where issue data is sensitive, all pages should be accessed via HTTPS.

The process of enabling SSL access is specific to each application server, but the process for specifying which pages require protection is generic.

On this page:

Running JIRA over HTTPS

The following flowchart shows the process involved in configuring HTTPS on Tomcat. Click the links below this chart to go to the instructions for that step.

• Configure HTTPS in Tomcat
• Generate Self-Signed Certificate
• Obtain CA Certificate
• Import Certificate into the Trust-store
• Requiring HTTPS for certain pages (Redirecting certain pages to HTTPS)

Configure HTTPS in Tomcat

Edit conf/server.xml, and at the bottom before the </Service> tag, add this section (or uncomment it where you find it) in Tomcat 6:

<Connector port="8443" maxHttpHeaderSize="8192" SSLEnabled="true"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" />

This enables SSL access on port 8443 (the default for HTTPS is 443, but just as Tomcat uses 8080 instead of 80 to avoid conflicts, 8443 is used instead of 443 here).

^Back to the flowchart

Generate Self-Signed Certificate

The following approach to create the certificate uses Java's keytool, and has been formatted for use with Java 1.6.
There are other tools for generating certificates such as openSSL which are not discussed in this procedure.

What is your first and last name?

Windows Standalone

"<install_dir>\jre\bin\keytool" -genkey -alias tomcat -keyalg RSA

Windows WAR/EAR

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA

Unix/Linux

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

This will create (if it doesn't already exist) a new .keystore file located in the home directory of the user you used to run the keytool command.

You will now need to export the certificate to make it ready for importing into the Trust-store with the following command:

Windows Standalone

"<install_dir>\jre\bin\keytool" -export -alias tomcat -file file.cer

Windows WAR/EAR

"%JAVA_HOME%\bin\keytool" -export -alias tomcat -file file.cer

Unix/Linux

$JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer

Next, import the certificate into the Trust-store.

^Back to the flowchart

Obtain CA Certificate

Digital Certificate that are issued by trusted 3rd party CAs (Certification Authority) provide verification that your Website does indeed represent your company, thereby verifying your company's identity. Many CAs simply verify the domain name and issue the certificate, whereas other such as VeriSign verifies the existence of your business, the ownership of your domain name, and your authority to apply for the certificate, providing a higher standard of authentication.

A list of CA's can be found here.
Some of the most well known CAs are:

• Verisign
• Thawte
• CAcert (relatively new CA, providing free CA certificates)

Next, import the certificate into the Trust-store.

^Back to the flowchart

Import Certificate into the Trust-store

Assuming your certificate is called "file.cer" whether obtained by a CA or self-generated, the following command will add this certificate to the Trust-store:

Windows Standalone

"<install_dir>\jre\bin\keytool" -import -alias tomcat -file file.cer -keystore "<install_dir>\jre\lib\security\cacerts"

Windows WAR/EAR

"%JAVA_HOME%\bin\keytool" -import -alias tomcat -file file.cer -keystore "%JAVA_HOME%\jre\lib\security\cacerts"

Unix/Linux

$JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer -keystore $JAVA_HOME/jre/lib/security/cacerts

Next, proceed to the step on redirecting certain pages to HTTPS.

^Back to the flowchart

Redirecting certain pages to HTTPS

Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8080) are still available. In most situations one wants these URLs to continue working, but for some to redirect to their https equivalent. This is done by editing WEB-INF/web.xml, and adding the following section at the end of the file, before the closing </web-app>:

<security-constraint>
<web-resource-collection>
<web-resource-name>all-except-attachments</web-resource-name>
<url-pattern>*.js</url-pattern>
<url-pattern>*.jsp</url-pattern>
<url-pattern>*.jspa</url-pattern>
<url-pattern>*.css</url-pattern>
<url-pattern>/browse/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

This means that all URLs except attachments are redirected from HTTP to HTTPS. IE has a bug which prevents attachments like .doc files being viewed via HTTPS if SSL protection is forced in web.xml.

Once this change is made, restart JIRA and access http://localhost:8080. You should be redirected to https://localhost:8443/secure/Dashboard.jspa. The port it redirects to is determined by the redirectPort value you specify in the server.xml file in the HTTP Connector stanza.

There does not seem to be an easy way to make subsequent pages revert to HTTP after logging in via HTTPS - see JRA-7250

トラブルシューティング

Here are some troubleshooting tips if you are using a self-signed key created by keytool, as described above.

When you enter "https://localhost:8443" in your browser, if you get a message such as "Cannot establish a connection to the server at localhost:8443", look for error messages in your logs/catalina.out log file. Here are some possible errors with explanations:

SSL + Apache + IE problems

Some people have reported errors when uploading attachments over SSL using IE. This is due to an IE bug, and can be fixed in Apache by setting:

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

Google has plenty more on this.

Can't find the keystore

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

これは、Tomcat がキーストアを見つけられなかったことを意味します。キーツール ユーティリティは、現在のユーザーのホーム ディレクトリに .keystore という名称のキーストアをファイルとして作成します。Unix / Linux ではホーム ディレクトリは多くの場合 /home/<username> です。Windows では多くの場合 C:\Documents And Settings\<UserName> です。

Make sure you are running JIRA as the same user who created the keystore. If this is not the case, or if you are running JIRA on Windows as a service, you will need to specify where the keystore file is in conf/server.xml. Add the following attribute to the connector tag you uncommented:

keystoreFile="<Keystore ファイルの場所>"

間違ったパスワード

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

"changeit" 以外のパスワードが使われています。Tomcat のキー パスワードとキーストア パスワードの両方で "changeit" を使用するか、異なるパスワードを使用する場合は、前述のように Connector タグの keystorePass 属性にそれを指定する必要があります。

パスワードが一致しません

java.io.IOException: Cannot recover key

Tomcat のキーストアパスワードとキーパスワードに異なるパスワードが使われていることを意味します。この二つのパスワードは同一でなければなりません。

Wrong certificate

javax.net.ssl.SSLException：有効化されている SSL 暗号化スイートと一致する、利用可能な証明書がありません。

キーストア内に複数の証明書がある場合、conf/server.xml 内の SSL Connector タグで指定がある場合を除き、Tomcat は最初に返された証明書を使用します。

次の例に示すように、コメントを解除した Connector タグに 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"/>