Running JIRA over SSL or HTTPS

Running JIRA over SSL or HTTPS

Running JIRA (6.4) over SSL or HTTPS

Atlassian applications allow the use of SSL within our products, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian cannot guarantee providing any support for it.

  • If assistance with conversions of certificates is required, please consult with the vendor who provided the certificate.
  • If assistance with configuration is required, please raise a question on Atlassian Answers.

The instructions on this page describe how to configure JIRA to enable access via HTTPS (HTTP over SSL) by configuring Apache Tomcat with HTTPS. This procedure only covers the common installation types of JIRA. It is by no means a definitive or comprehensive guide to configuring HTTPS and may not be applicable to your specific setup.

Why should you enable HTTPS access to JIRA?
HTTPS is a good way to safeguard your JIRA data and user logins from being intercepted and read by outsiders.

Before you begin

Please note the following before you begin:

  • Atlassian Support will refer SSL support to the Certificate Authority (CA) that issues the Certificate. The SSL-related instructions on this page are provided as a reference only.
  • For JIRA installations installed using Windows Installer:
    • The ‘Windows Installer‘ installs its own Java Runtime Environment (JRE) Java platform, which is used to run Tomcat. When updating SSL certificates, please do so in this JRE installation.
    • In this document, the term <jira-install-dir> refers to the JIRA Installation Directory itself.

On this page:

Related topics:

If hosting JIRA behind a reverse-proxy such as Apache, please follow our Integrating JIRA with Apache using SSL documentation.

Generate the Java KeyStore

In this section, you will create a Java Key Store (JKS) which will hold your SSL certificates. The SSL certificates are required in order for SSL to work in JIRA. In the SSL world, certificates fall into two major categories:

Certificate Description When to Use Steps
Self-signed These are certificates that have not been digitally signed by a CA, which is a method of confirming the identity of the certificate that is being served by the web server. They are signed by themselves, hence the name self-signed. Test, dev or internal servers only. 1 – 13
CA-signed A certificate that has had its identity digitally signed by a Certificate Authority (CA). This will allow browsers and clients to trust the certificate. Production servers. 1 – 21

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.

Some of the most well known CAs are:

We recommend using a CA-signed certificate.

If you’re unable to install Portecle on the server or prefer the command line please see our Command Line Installation section below.

  1. Download and install the Portecle app onto the server that runs JIRA.
    (warning) This is a third-party application and is not supported by Atlassian.
  2. Run the App as an Administrator, so it will have the appropriate permissions. Also, ensure the <JAVA_HOME> variable is pointing to the same version of Java that JIRA uses. See our Setting JAVA_HOME docs for further information on this.
    (info) If running on a Linux/UNIX server, X11 will need to be forwarded when connecting to the server (so you can use the GUI), as below:

    1
    ssh -X user@server
  3. Select the Create a new Keystore option:
  4. Select the type JKS and OK:
  5. Select the Generate Key Pair button:
  6. Select the RSA algorithm and your preferred Key Size – the standard is currently 2048:
  7. Make sure the Signature Algorithm is "SHA256withRSA" and then edit the certificate details, as per the below example and select OK:

    (warning) The Common Name MUST match the server’s URL, otherwise errors will be displayed in the browser.
    (info) If you would like to use SHA256withRSA, please use the appropriate Signature Algorithm, and refer to: Security tools report the default SSL Ciphers are too weak
  8. Choose an alias for the certificate – for example jira.
  9. Enter a password for the KeyStore (the default password used is typically changeit).
  10. The Key Pair Generation will report as successful, as per the below example:
  11. Save the KeyStore in <JIRA_HOME>/jira.jks, ensuring the use the same password in step 11. This can be done by File > Save Keystore.

    If using a self-signed certificate certificate, proceed to Configuring your web server using the JIRA configuration tool, otherwise continue on.

  12. We need to generate a Certificate Signing Request for the CA to sign and confirm the identity of the certificate. To do so, right click on the certificate and choose Generate CSR. Save it in <JIRA_HOME>/jira.csr.
  13. Submit the Certification Request (CSR) to a Certificate Authority for signing. They will provide a signed certificate (CA reply) and a set of root/intermediate CA certificates.
  14. Import the root and/or intermediate CA certificates with Import Trusted Certificate, repeating this step for each certificate.
  15. Import the signed certificate by right clicking on the jira certificate and selecting Import CA Reply:
  16. Select the certificate provided by the CA, which should be jira.crt. This will respond with CA Reply Import successful.
  17. Verify this by checking Tools > Keystore Report. It should display the certificate as a child of the root certificates.
  18. Save the KeyStore and proceed to the next section.

Configuring your web server using the JIRA configuration tool

In this section, you will finish setting up SSL encryption for JIRA, by configuring your web server using the JIRA configuration tool. For more information on the JIRA configuration tool, see Using the JIRA Configuration Tool.

To configure your web server using the JIRA configuration tool:

  1. Run the JIRA configuration tool, as follows:
  2. Click the Web Server tab.
    Screenshot: JIRA configuration tool — ‘Web Server’ tab
  3. Fill out the fields as follows:
    Field Value
    Control Port Leave as default. You can change the port number if you wish. See Changing JIRA’s TCP Ports .
    Profile A profile is a preset web server configuration. You can pick from the four following values:

    • Disabled
    • HTTP only
    • HTTP & HTTPS (redirect HTTP to HTTPS)
    • HTTPS only

    To run JIRA over HTTPS, you must pick either ‘HTTP & HTTPS’ or ‘HTTPS’.
    Pick ‘HTTP & HTTPS’ if you want to run JIRA over HTTPS but you have users that access JIRA via HTTP. If you pick ‘HTTP & HTTPS’, users who try to access JIRA via HTTP will be redirected to the HTTPS address.
    HTTP port Leave as default (8080). You can change the port number if you wish. See Changing JIRA’s TCP Ports .
    This will be disabled if you set the Profile to ‘HTTPS only’.
    HTTPS port Leave as default (8443). You can change the port number if you wish. See Changing JIRA’s TCP Ports .
    Keystore path Specify the location of the keystore of your certificate. This will have been chosen when the keystore was saved in step 13 and should be <JIRA_HOME>/jira.jks.
    Keystore password Specify the password for your keystore. If you generated a self-signed certificate, this is the password you specified for the key and keystore when generating the certificate in step 13.
    Keystore alias Each entry in the keystore is identified by an alias. We recommend using jira for this certificate as in step 10.
  4. Click the Check Certificate in Key Store button to validate the following:
    • Test whether the certificate can be found in the key store.
    • Test whether keystore password works.
    • Test whether key can be found using key alias.
  5. Click the Save button to save your changes.

Advanced configuration

Running more than one instance on the same host

When running more than one instance on the same host, it is important to specify the address attribute in the <JIRA_INSTALLATION>/conf/server.xml file because by default the connector will listen on all available network interfaces, so specifying the address will prevent conflicts with connectors running on the same default port. See the Tomcat Connector documentation for more about setting the address attribute in The HTTP Connector Apache Tomcat 7 docs.

Command Line Installation

Create the Keystore

  1. Generate the Java KeyStore (JKS):
    1
    <JAVA_HOME>/keytool -genkeypair -alias jira -keyalg RSA -sigalg SHA256withRSA -keystore <JIRA_HOME>/jira.jks

    (info) Instead of first and last name, enter the server URL, excluding “https://” (e.g.: jira.atlassian.com).

  2. Enter an appropriate password (e.g.: changeit).
  3. Create the CSR for signing, using the password from step 2:
    1
    <JAVA_HOME>/keytool -certreq -keyalg RSA -alias jira -keystore <JIRA_HOME>/jira.jks -file jira.csr
  4. Submit the CSR to the CA for signing. They will provide a signed certificate and a root and/or intermediate CA.
    (warning) If the certificate will not be signed, skip to step 7.
  5. Import the root and/or intermediate CA:
    1
    <JAVA_HOME>/keytool -import -alias rootCA -keystore <JIRA_HOME>/jira.jks -trustcacerts -file root.crt
  6. Import the signed certificate (this is provided by the CA):
    1
    <JAVA_HOME>/keytool -import -alias jira -keystore <JIRA_HOME>/jira.jks -file jira.crt
  7. Verify the certificate exists within the keystore.
    1
    <JAVA_HOME>/keytool -list -alias jira -keystore <JIRA_HOME>/jira.jks

    This must be a PrivateKeyEntry, if it is not the certificate setup has not successfully completed. For example:

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

Update Tomcat with the Keystore

  1. Create a backup of <JIRA_INSTALL>/conf/server.xml before editing it.
  2. Edit the HTTPS connector so that it has the parameters that point to the key store:
    1
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
    2
                  maxHttpHeaderSize="8192" SSLEnabled="true"
    3
                  maxThreads="150" minSpareThreads="25"
    4
                  enableLookups="false" disableUploadTimeout="true"
    5
                  acceptCount="100" scheme="https" secure="true"
    6
                  clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"
    7
                  keyAlias="jira" keystoreFile="<JIRA_HOME>/jira.jks" keystorePass="changeit" keystoreType="JKS"/>

    (info) Ensure to put the appropriate path in place of <JIRA_HOME> and change the port as needed.

  3. Edit the HTTP connector so that it redirects to the HTTPS connector:
    1
    <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"/>

    (info) Ensure the <PORT_FROM_STEP_1> is change to the appropriate value. In this example it would be 8443.

  4. Save the changes to server.xml.
  5. If redirection to HTTPS will be used (this is recommended), edit the <JIRA_INSTALL>/atlassian-jira/WEB-INF/web.xml file and add the following section at the end of the file, before the closing </web-app>. In this example, all URLs except attachments are redirected from HTTP to HTTPS.
    1
    <security-constraint>
    2
    <web-resource-collection>
    3
    <web-resource-name>all-except-attachments</web-resource-name>
    4
    <url-pattern>*.jsp</url-pattern>
    5
    <url-pattern>*.jspa</url-pattern>
    6
    <url-pattern>/browse/*</url-pattern>
    7
    </web-resource-collection>
    8
    <user-data-constraint>
    9
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    10
    </user-data-constraint>
    11
    </security-constraint>
  6. Restart JIRA after you have saved your changes.

(info) You can also redirect users from HTTP URLs to HTTPS URLs by choosing the ‘HTTP & HTTPS’ profile in the JIRA configuration tool. However, if you want to only redirect certain pages to HTTPS, you can do this manually. To do this, select the ‘HTTPS only’ profile in the JIRA configuration tool and save the configuration.

Troubleshooting

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

When you enter “https://localhost:<port number>” 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.

Click here to expand…
  • 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:
    1
    BrowserMatch ".MSIE." \
    2
    nokeepalive ssl-unclean-shutdown \
    3
    downgrade-1.0 force-response-1.0

    Google has plenty more on this.

  • Can’t find the keystore:
    1
    java.io.FileNotFoundException: /home/user/.keystore (No such file or directory)

    This indicates that Tomcat cannot find the keystore. The keytool utility creates the keystore as a file called .keystore in the current user’s home directory. For Unix/Linux the home directory is likely to be /home/<username>. For Windows it is likely to be 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:

    1
    keystoreFile="<location of keystore file>"

    This can also happen (“Cannot find /root/.keystore”) if you add a keystoreFile attribute to the http connector in server.xml instead of the https connector.

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

    This error will happen if you have identical names or fingerprints, which is the result of attempting to recreate the cert in your existing keystore. If you need to recreate or update the Cert, you may remove the existing keystore and creating a fresh, new keystore. In this case, creating a new keystore and adding the related certs will fix the issue. The default path for it in this documentation is $JAVA_HOME/jre/lib/security/cacerts

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

    You used a different password than “changeit”. You must either use “changeit” for both the keystore password and for the key password for Tomcat, or if you want to use a different password, you must specify it using the keystorePass attribute of the Connector tag, as described above.

  • Passwords don’t match:
    1
    java.io.IOException: Cannot recover key

    You specified a different value for the keystore password and the key password for Tomcat. Both passwords must be the same.

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

    If the Keystore has more than one certificate, Tomcat will use the first returned unless otherwise specified in the SSL Connector in conf/server.xml.

    Add the keyAlias attribute to the Connector tag you uncommented, with the relevant alias, for example:

    1
    <Connector port="8443" maxHttpHeaderSize="8192"
    2
    maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    3
    enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true"
    4
    acceptCount="100" scheme="https" secure="true"
    5
    clientAuth="false" sslProtocol="TLS"
    6
    keystoreFile="/opt/local/.keystore"
    7
    keystorePass="removed"
    8
    keyAlias="tomcat"/>
  • Using Apache Portable Runtime:APR uses a different SSL engine, and you will see an exception like this in your logs
    1
    SEVERE: Failed to initialize connector [Connector[HTTP/1.1-8443]]
    2
    LifecycleException:  Protocol handler initialization failed: java.lang.Exception: No Certificate file specified or invalid file format

    The reason for this is that the APR Connector uses OpenSSL and cannot use the keystore in the same way. You can rectify this in one of two ways:

    • Use the Http11Protocol to handle SSL connections — Edit the server.xml so that the SSL Connector tag you just uncommented specifies the Http11Protocol instead of the APR protocol
      1
      <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
      2
        maxHttpHeaderSize="8192" SSLEnabled="true" keystoreFile="${user.home}/.keystore"
      3
        maxThreads="150" enableLookups="false" disableUploadTimeout="true"
      4
        acceptCount="100" scheme="https" secure="true"
      5
        clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"/>
    • Configure the Connector to use the APR protocol — This is only possible if you have PEM encoded certificates and private keys. If you have used OpenSSL to generate your key, then you will have these PEM encoded files – in all other cases contact your certificate provider for assistance.
      1
      <Connector
      2
        port="8443" maxThreads="200"
      3
        scheme="https" secure="true" SSLEnabled="true"
      4
        SSLCertificateFile="${user.home}/certificate.pem"
      5
        SSLCertificateKeyFile="${user.home}/key.pem"
      6
        clientAuth="optional" SSLProtocol="TLSv1"/>
  • Enabling Client Authentication: To enable client authentication in Tomcat, ensure that the value of the clientAuth attribute in your Connector element of your Tomcat’s server.xml file is true.
    1
    <Connector
    2
        ...
    3
        clientAuth="true"
    4
        ... />

    For more information about Connector element parameters, please refer to the SSL Configuration HOW-TO Tomcat 7 documentation.

  • Using StartCom Certificate: Unable to get Application Link to work properly with certain features such as Gadgets and Macros not working over SSL. There is a known bug in JRA-33643 with a workaround to manually import root certificates to Java certificates store.

SOURCE: https://confluence.atlassian.com/jira064/running-jira-over-ssl-or-https-720411727.html

 

Comments are closed.