Documentation for JIRA 6.3. Not using this? See below:
(JIRA 6.2.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

Icon

Atlassian applications allow the use of SSL within our products, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian can not 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 run JIRA over SSL or HTTPS 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 run JIRA over SSL or 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.

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:

Icon

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:

CertificateDescriptionWhen to UseSteps
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-signedA 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.

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

We recommend using a CA-signed certificate.

Icon

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:

  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 a Key Size of 2048:
  7. Make sure the Signature Algorithm is "SHA1withRSA" 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: Default SSL ciphers 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.

    Icon

    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 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:

    FieldValue
    Control PortLeave as default. You can change the port number if you wish. See Changing JIRA's TCP Ports .
    ProfileA 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 portLeave 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 portLeave as default (8443). You can change the port number if you wish. See Changing JIRA's TCP Ports .
    Keystore pathSpecify 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 passwordSpecify 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 aliasEach 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):

    (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:

  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:

  6. Import the signed certificate (this is provided by the CA):

  7. Verify the certificate exists within the keystore.

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

    jira, Jan 1, 1970, PrivateKeyEntry,
    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:

    (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:

    (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>/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.

  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:

    Google has plenty more on this.

  • Can't find the keystore:

    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:

    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:

    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:

     

    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:

    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:

    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:

     <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"/>
    
  • Using Apache Portable Runtime:

    APR uses a different SSL engine, and you will see an exception like this in your logs

     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

    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

      <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
        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"/>
      
    • 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.

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

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

    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.
  • No labels

67 Comments

  1. f

    If you have a signed x509 for your URL already, there is no easy one step method to import the key and the cert to Java/Tomcat. The problem arises in the way Java's keystore uses PKS mode for keys, where as Apache and X509 stores keys in PEM mode. (Sorry, I can't give you a more techincal explanation).
    If you import the wrong key type the error message you will get from mozilla is:
    "Mozilla and localhost cannot communicate securely because they have no common encryption algorithms".

    IE will display a window with only a few squares but no error message.

    The fix for this can be found here: http://mail-archives.apache.org/mod_mbox/jakarta-tomcat-user/200408.mbox/%3C20040805090009.75478.qmail@web12308.mail.yahoo.com%3E

    This is geared towards older Tomcat 4.1 and uses a free 3rd party tool.

  2. We are using Jira 3.5 with Tomcat 5.5, and have it starting as a service within Windows.  I made the changes above to add HTTPS, using a self-signed cert for now, and restarted the service.   It still works for port 8080, but 8443 only works if I stop the service and start it using the startup.bat command.  Any suggestions?

     Thanks,

    tracy

    1. Hi Tracy,

      Sorry about the late reply. The problem here is that the Tomcat server is looking for the keystore file in the user's home directory (Documents And Settings/<UserName>). However the Windows Service starts Tomcat using the System account not your user account, this then means Tomcat can't find the file.

      So in order to get this to work on Windows you will need to explicitly set the location of the keystore file. To do this:

      1. Find the .keystore file in your user directory, copy its location
      2. Open conf/server.xml
      3. In the connector tag that you uncommented add the parameter:
                          keystoreFile="<location of keystore file>"
      4. Restart Jira Service

      Thanks,
      Brian

  3. Hi, i have just finished installing tomcat 5.5.17 however when i am finished setting up my cert (no errors) i can only browse port 8443 over http not https (uncommented the ssl section in server.xml) also added a direct mapping to the keystore

    Any ideas what could be wrong?

    TIA

    Nick

    1. Double-check your server.xml. It sounds like you changed the HTTP connector from 8080 to 8443.

      Cheers,
      Jeff

  4. Really minor point..
    It would be nice if the <security-constraint> section for the web.xml file was added as a commented-out section in the supplied web.xml that comes with Jira.

    • We will have to add it manually every time we upgrade, so it would be useful to have it already there so we can just remove the comment tags.
    • I notice this is already done for some optional elements of that file, eg WebSphere config.
  5. Okay, after fighting this for a good day, I finally got it working with my existing ssl certificate.  I have a *.<domain name> certificate with the cert and private keys in separate files.  After several searches and trial and error, turns out you can just use the openssl tool to create a PKCS12 keystore which contains your private key and then tell JIRA to use that keystore.  This site (https://wiki.systemsx.ch/display/ITDOC/Import+an+openssl+generated+key+into+a+tomcat+application) was the most help for me.  But basically, here are the steps...

    1. If your key does not have a password (mine did not) create a DES encrypted version using the same password you plan to use for your keystore...
    2.  Ensure you have a file containing the chain for your certificate, starting with your server certificate up to the root certificat
    3. Create the PKCS12 keystore containing both your private key and the public certificate chain.  Use the same password for the export as you used for your private key
    4. Update the server.xml as noted above ensuring all of the following are defined...
      1. keystoreFile (points to the keystore.pkcs12 file you created above)
      2. keystoreType="PKCS12"
      3. keystorePass (the password you used above)

         

    1. Anonymous

      Thanks much for posting this! That was the solution for us!

    2. Anonymous

      Bingo!  Thank you muchly.  (In my case I didn't need the root certificate file)

    3. Anonymous

      You da man!! Thank you so much for these instructions, it helps us with GoDaddy provided certificate.

      Atlassian: This page really needs review and update.. 

    4. Anonymous

      Thanks alot, this worked for me (smile)

      (v5.1.4)

      Only trouble I had was, that in step 2 the files didnt "merge" properly. There was no linebreak between a -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- line. So make sure you quickly look inside the cert.pem to see if everything looks right.

  6. Anonymous

    Two things that should be mentioned.

    I think this document could be improved it if explicitly named a keyfile path by default.  Almost every setup out here will have Tomcat running under a system account (Win) or "tomcat" (Linux).

    The self-signed certificate generated above will only be valid for 90 days by default.  I used this command (expires in 10 years):

    $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -dname "cn=Stewart Vardaman, ou=STG, o=Echostar, c=US" -validity 3650

  7. Anonymous

    One more comment: I personally wouldn't keep my keystore file in "/home/idaniel/.keystore" -- say ldaniel leaves company and someone in IT removes his user dir.  Next time Tomcat is restarted the SSL side will die.

  8. Anonymous

    For those running Windows, SSL certs are typically stored or archived in PFX files.  (Microsoft's PFX Keystore is PKCS#12 format and may alternatively have a .p12 file extension.)

    I've found that there is no need for use of keytool or openssl to get JIRA / Tomcat to function using the Windows native PFX SSL archive files.

    The secret is the use of the keystoreType attribute within the connector set to "PKCS12":

    <Connector port="8443" maxHttpHeaderSize="8192"
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" disableUploadTimeout="true"
            acceptCount="100" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"
            keystoreFile="C:\JIRA_.example.com.pfx"
            keystorePass="*******"
            keystoreType="PKCS12" />

    After importing a cert, purchased from GoDaddy, into the Windows certificate repository (via MMC cert snap-in), I then exported the PFX cert backup.  In this particular case, this was successfully setup with a wildcard domain cert.

    Jonathan B.

    1. In JIRA 4.0+, it is still necessary to use the keytool to import your cert into the JRE used by Jira 4.0 (typically in jira4.0\jre\lib\security\cacerts) keystore even when using .pfx files, in addition to the above server.xml changes. From my initial testing, it appears that can be done via the following:

      Note that you are doing an -importkeystore because a .pfx file is itself a keystore, not just a plain cert.

      Failing to do so will lead to the issue described here

      1. Anonymous

        keytool -importkeystore -deststorepass changeit -destkeystore d:\path\to\jira4.0\jre\lib\security\cacerts

        -srckeystore d:\path\to\my.pfx -srcstoretype PKCS12 -srcstorepass <password_for_pfx>



        got syntax erro after executing above command...

        1. Anonymous

          Let me guess... you literally typed in d:\path\to\... without dedicating a single brain cell towards thinking about what that actually means?

  9. Anonymous

    Hi Radek here from MoneyMate. We're currently evaluating JIRA and CONFLUENCE - both on UBUNTU Linux 64-bit connected to MySQL. HTTP and HTTPS access is working fine. My question is: is it there a possibility how to define a next HTTPS connector with a different certificate (on a different port of course)? What we want is to have two sites - for example https://jira.mm.com and https://jira.moneymate.com pointed to the same JIRA (or CONFLUENCE) installation with correct certificates. Can I duplicate HTTPS section in server.xml or ...? Any idea would be appreciated.

  10. Anonymous

    This documentation could be inproved, it is somewhat confusing.

    When asked to "What is your first and last name" make sure you enter in the DNS name that you will use to access the host.

    Why on earth would I have to use the DNS name in place of 'first and last name'?

    1. Anonymous

      Why on earth would I have to use the DNS name in place of 'first and last name'?

      Because that's the way how server certificates work. You should better educate yourself on the topic of server certificates.

  11. Hi,

    In server.xml, does SSLEnabled="true" need to be added to get a self-signed cert to work?  I couldn't get https://localhost:8443 to function; but, adding that parameter seemed to do the trick.  The Confluence documentation talks about it at http://confluence.atlassian.com/display/DOC/Adding+SSL+for+Secure+Logins+and+Page+Security.

    Thanks,

    Steve

    1. I would say that it does - I had the same issue and your suggestion above resolved it.

      I'm using Jira 4.1 if that makes any difference.

      Thanks for taking the time to post your solution here after you solved the issue as it saved me a great deal of time!

  12. Trying with a company certificate now and I get the error in the logs:

    LifecycleException:  Protocol handler initialization failed: java.io.FileNotFoundException: C:\Documents and Settings\Default User\.keystore (The system cannot find the file specified)

    Which is true because this file does not exist - do I need a keystore with an existing .cer file? If so, how do I create one that corresponds with the .cer file I have?

  13. I get the 5 squares in IE (8) as well. I've checked through all the config steps mentioned in here and hope I did "everything" right, but still get the 5 squares in IE, and a file download octet stream in FF (latest). What other reasons would there be that could make this happen? I'm not seeing errors in my logs.

    1. We've found the solution.

      There are TWO connector blocks in server.xml. One for port 8080 (or another as you need), and one for port 8443 (or other).

      The SSL configs need to be added to the second connector block. While the document above does show you the 8443 connector block, it omits to remind you to not change the 8080 block. The doc also does not refer to the comments in server.xml that you can read which also tell you to edit the 8443 block.

      Hopefully the moderator of this page can add an info comment before the place where the block mods are shown to alert the person doing the mods that they should do this in the second block. Also, perhaps some of the comments from the server.xml file can be brought into this documentation and explained/elaborated in more detail.

      May I also ask that the 3.13.5 documents on SSL config are updated? Those do not allow comments anymore, but the suggestions are probably just as relevant there.

      1. Right, it works the same way for Confluence too...two separate connectors: one for http, one for https. Regarding the keystore, I created the keystore in another location from the default. The SSL connector needs the location of the keystore if it is not the default (the documentation discusses this). Below is a copy of our SSL connector in the server.xml file. I did put an extra parameter in there for the IP address to listen on. This server has multiple IP's and this way it only listens on one of them on port 443 (the first http connector also needs to be modified with the redirect SSL port and, in my case, the address parameter):

        <Connector port="443" maxHttpHeaderSize="8192"
                      address="192.168.1.101"
                      maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                      enableLookups="false" disableUploadTimeout="true"
                      acceptCount="100" scheme="https" secure="true" SSLEnabled="true"
                      clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"
                      keystorePass="password" keystoreFile="D:\JIRA\keystore\.keystore" />

  14. Note. If you have a Java jdk installed and run the keytool from the %java_home% directory instead of <install_dir>/jre/bin with a Jira STANDALONE installation, the commands will run successfully, however, tomcat will throw a FileNotFoundException (Access is Denied) error when starting up Jira. I did this accidentally and found that I needed to revert to a previous snapshot and then begin again, in the correct directory. Just in case anyone else does the same stupid mistake, is there an easier way to patch over the keystore file or go through the steps without needing to revert?

    1. Right Chalise, that makes sense. The JIRA Standalone installation uses its included JDK installation, not one installed on the system (if you have one) which is probably referenced by the %java_home% environment variable.

      But, I'm a little confused why you had to revert to a snapshot for this. It sounds like you just installed a certificate in the wrong store using the wrong JDK installation, that's all. Couldn't you just delete the cert from the wrong keystore or even just delete the wrong keystore entirely (assuming there are no other needed certs in there)?

      Then, just run the keytool from the included JRE directory and import the certificate to a new keystore and reference that in the server.xml file (make sure the password for the cert and the keystore are the same).

      Here is some step-by-step documentation I created to import a certificate and enable SSL with a JIRA Standalone installation at D:\JIRA:

      1. Creating CA cert per http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html:
        1. Create a local certificate: D:\JIRA\JIRA-Enterprise-4.1.1\jre\bin\keytool -genkey -alias jira -keyalg RSA -keystore D:\JIRA\keystore\.keystore
          First & Last Name = server.domain.com
          Organizational Unit = Department
          Organization = Organization
          City = MyCity
          State = MyState
          Country Code = US
          Password should be same as keystore password
          (keystore will then be created at D:\JIRA\keystore\.keystore - verify NTFS permissions allow the JIRA Tomcat service to access)
        2. Create CSR file to send to central authority: D:\JIRA\JIRA-Enterprise-4.1.1\jre\bin\keytool -certreq -keyalg RSA -alias jira --keystore  D:\JIRA\keystore\.keystore -file jiracertrequest.csr
        3. Purchase certificate from central authority and send contents of CSR file
        4. Download Root Certificate from the central authority and put into a file called rootcert.cer (this step was not needed as root cert already existed by default)
        5. Import Root Cert (this step was not needed as root cert already existed by default):
          keytool --import --alias root --keystore D:\JIRA\keystore\.keystore --trustcacerts --file d:\rootcert.cer
        6. When new certificate arrives from central authority, copy contents to new file called issuedcert.cer and Import New Cert: 
          D:\JIRA\JIRA-Enterprise-4.1.1\jre\bin\keytool --import --alias jira --keystore D:\JIRA\keystore\.keystore --trustcacerts --file d:\issuedcert.cer
        7. Uncommented lower section of conf/server.xml, and added lines:
          SSLEnabled="true" keystorePass="password" keystoreFile="D:\JIRA\keystore\.keystore" />
        8. Added SSL site wide per http://confluence.atlassian.com/display/DOC/Adding+SSL+for+Secure+Logins+and+Page+Security
          Edit the confluence/WEB-INF/web.xml file and add the following declaration to the end, before the </web-app> tag:
          <security-constraint>  
          <web-resource-collection>
              <web-resource-name>Restricted URLs</web-resource-name>
              <url-pattern>/</url-pattern>
            </web-resource-collection>
            <user-data-constraint>
              <transport-guarantee>CONFIDENTIAL</transport-guarantee>
            </user-data-constraint>
          </security-constraint>
        9. Restart JIRA Tomcat Service

      Hope this helps!

      Steve

      1. Thanks Steve, it ended up working perfectly when I followed the instructions correctly. (Of course, right?)

        I was confused originally with whether or not I could safely delete the keystore file - clearly it wouldn't have caused an issue if I had. However, I wasn't sure when I was first setting it up if that would cause problems with a newly generated file if I didn't delete the first one "correctly". Turns out there wasn't much cause for concern. Anyway, regardless, thank you very much for the help. 

  15. Anonymous

    We got JIRA to start with SSL on port 8443 on a cloud instance. Our objective is to start JIRA on accept HTTPS on port 443, we tried replacing 8443 with 443 in the server.xml. This did not work as JIRA complained it does not have permission to start on port 443.

    Is starting JIRA as root an option here? or is there any other way to achieve the same.

    Thanks in advance.

    1. Anonymous

      I have the same problem, JIRA only works in SSL using port 8443, other than that JIRA

      doesnt work anymore.

      Is there any way we can solve this issue? I really want to use port 443 without any security risk.

      Thanks

      1. That's not accurate. JIRA does work on port 443. Verify that no other process is using that port.

        I have JIRA running on a server that also has Confluence...both are using port 443 (each with a different IP). 
        SSL is enabled site-wide.

        Make sure you uncomment the section at the bottom of the server.xml file that states, "To run JIRA via HTTPS:"

        I also have IIS running on the server to handle traffic to our JIRA URL using port 80. It simply redirects it to port 443.

        The code you need is in my post above from June 15th.

        Good luck!

        1. Anonymous

          JIRA may work on Port 443, but if the operating system does not permit it to bind there, SOL. I solved this on our evaluation system like this:

          $ sudo apt-get install openbsd-inetd

          $ tail -1 /etc/inetd.conf

          443     stream  tcp     nowait  jira-proxy      /bin/nc nc 127.0.0.1 4443

          This may or may not perform well enough, but there’s no way I’m going to let any Java™ run as root. I’d be more comfortable with bridging over Apache anyway, but the docs on that are a bit sparse when SSL comes into the mix.

          Furthermore, JIRA’s HTTPS, as opposed to Apache’s, still throws errors because it doesn’t include the intermediate certificate. Where’s the equivalent setting of the SSLCertificateChainFile option of Apache?

  16. Anonymous

    I have configured jira in separate ip address wherever we can access its successfully completed now i want to configure my own mail id in jira mail configuration. how can i configure tell me step by step instruction...

  17. Anonymous

    when you receive this error,

    keytool error: java.lang.Exception: Certificate not imported, alias <tomcat> already existskeytool error: java.lang.Exception: Certificate not imported, alias <tomcat> already exists
    keytool error: java.lang.Exception: Certificate not imported, alias <tomcat> already exists

    you can delete the cert from keystore by following this step

    $JAVA_HOME/bin/keytool -keystore $JAVA_HOME/jre/lib/security/cacerts -delete -alias tomcat

    hope this helps

    ur captch sucks

    1. Anonymous

      Nice, that helps!

  18. Would be great to take in mind if you are receiving this error

    That means that your instance is having hard time trying to find the right path to your certificate.

    Certificates you import should be in

    • "%JAVA_HOME%\jre\lib\security\cacerts"

    And another thing to take in mind is that we have to "Stores"

    • TrustStore
      • This will hold all certificates from other servers
    • KeyStore
      • This will have YOUR OWN certificate

    You could try this parameter on the JAVA_OPTS to set a custom PATH:

    TrustStore

    KeyStore

    Will Save all certificates from other servers

    Here is where you save your own certificate, that will be given to other servers

    -Djavax.net.ssl.trustStore=$TRUSTSTORE"

    -Djavax.net.ssl.keyStore=$KEYSTORE"

    -Djavax.net.ssl.trustStorePassword=changeit"

    -Djavax.net.ssl.keyStorePassword=changeit"

    Cheers!

  19. The new versions of Jira use the Tomcat APR library which means you cannot use the Java Keystore for SSL you must use OpenSSL compatible certificates and keys. Either disable the tomcat APR library from loading and use the native Java keystore functionality, or follow this guide to extract your existing private key and public certificate from your java keystore file: http://conshell.net/wiki/index.php/Keytool_to_OpenSSL_Conversion_tips

    The documentation really needs to be updated. The official documented steps are no longer valid since Jira 4.3.1: http://jira.atlassian.com/browse/JRA-24488

    You'll probably also need to end up downloading the Win32 Openssl binaries so you can do the key conversions.

    1. Anonymous

      I found this comment after spending way too long messing with the incorrect instructions above.

      It's worth noting that there's another directive, SSLCertificateChainFile, that's a path to an intermediate cert file if you have one of the pesky buggers.

      I did not have to perform any key format transforms with my GoDaddy cert - the .crt files for the public key and intermediate cert worked without an explicit PEM conversion.

  20. Anonymous

    Hello, I having a problem launching any HTTPS connections locally on my system. I can open if I speficy the 8443 port. ie http://mywebsite.com:8443/hlogin.jsp 

    Very new to this. I'm actually trying to rebuild a system that no loger is supported. It currently is in the DMZ and can access the internal network, but it will not open from the WWW either. The firewall etc is not blocking as it hasn't changed from the original system that died.

    thanks

    John

  21. Anonymous

    I work at a college.  We have been using JIRA Enterprise standalone version 3.13.5 for some time now.  When I first came on board, my goal was to move our existing JIRA setup off an old Linux box and put it on a Windows IIS 7 server, which I did successfully.  We use JIRA for lots of projects and continue to do so.

    However, my boss wants me to set our JIRA up for HTTPS.  So I followed this guide and the one found here: http://confluence.atlassian.com/display/JIRA/Integrating+JIRA+with+IIS -- all to no avail!  I created a cert using DigiCertsCA, added it to the keystore, and edited the server.xml file to accept it.  I also checked my bindings and pass-throughs in the IIS Manager.  Nothing helps.

    You can see that our JIRA works fine in HTTP: http://support.northark.edu:8080/

    But when you try to run HTTPS: http://support.northark.edu:8443/ -- that's where we run into trouble.  Used to, it would pop up a "certificate self-signed -- don't trust it!" error message, but now it doesn't even do that. 

    What am I doing wrong?

  22. Anonymous

    I also had some problems while following the instructions above for a Linux host and was able to resolve my problem.  The instructions are incomplete and/or make certain assumptions and need to be updated.

     

    In short, you must be sure to run the keytool commands shown above as the user you installed JIRA under (in my case that was a user called 'jira').  This is because tomcat / catalina expects the .keystore to be located in that user's home directory, otherwise you get errors in the catalina startup logs and the service won't start up successfully.

    Also, I had to ensure that the /home/jira directory existed (because in my case it did not, since my jira user is a service account and never supposed to directly log in) before i could create the .keystore files at that path.

    I second the person's opinion above, the "-validity 3650" should be added to the keygen command to make the certificate good for a longer period of time.

     

     

    My system is Ubuntu Server AMD64 10.04.3 LTS, running the Standalone instance of JIRA.  I followed the installation instructions on elsewhere on this wiki, so they are clearly in need of update to include these important details.

  23. Anonymous

    Does anyone know if it is possible to use a certificate from a Microsoft CA in a Domain and import it into a keystore for Tomcat /  Jira to use? And if so how? I have tried the import mentioned in this documentation, all is succesful but when I go to browse to the webpage the web page fails to load. All works well if I use a self signed cert, but I get a cert error before I continue to the web page.

  24. Anonymous

    After 3 hours experimenting .. here's my solution for creating a selfsigned certificate with JIRA 5 on windows server 2008 x64

    After getting most of the errors noted above (especially "java.io.IOException: jsse.invalid_ssl_conf")

    I found this solution (... means some unchanged part) :

    1. connector part of server.xml:

               <Connector ... protocol="org.apache.coyote.http11.Http11Protocol" keystoreFile="conf\keystore" keystorePass="changeit" keyAlias="tomcat" />

    2. Instead of doing the keytool -genkey, -export, -import sequence I created the keystore directly in the conf folder:

    keytool.exe  -genkey -keystore "C:\Program Files\Atlassian\JIRA\conf\keystore" -alias tomcat -v -storepass changeit -keyalg RSA -sigalg MD5withRSA -validity 4000

     

    (I also changed permissions of the file but don't think that was really neccessary)

    Dumping the store with: keytool.exe  -list -keystore "C:\Program Files\Atlassian\JIRA\conf\keystore" -v -storepass changeit 

    shows this (with the secret parts removed):

    Keystore-Typ: JKS
    Keystore-Provider: SUN
    ...
    Aliasname: tomcat
    Erstellungsdatum: ...
    Eintragstyp: PrivateKeyEntry
    Zertifikatskettenlõnge: 1
    Zertifikat[1]:
    Digitaler Fingerabdruck des Zertifikats: ...
             Unterschrift-Algorithmusname: MD5withRSA
             Version: 3

    Hope that helps others!!
    Harald

  25. Anonymous

    What is the best way to redirect everything to HTTPS while ignoring IE specific problems? If anything, I would love to break IE.

    Thanks.

     

  26. for those interested by the issues relating to running JIRA as a service on SSL, under Debian flavored linuxes (Ubuntu,...), you can also read this post on Stash 's section of atlassian answers, and the comments 

  27. Anonymous

    My JIRA Configuration Tool differs from the one shown above. Only the HTTP Port and Control Port options are available under the Web Server tab.  The command-line interface of does not allow the configuration of HTTPS/SSL either.  I am using JIRA 5.1.7 on Linux x86-64.

    I will have a go at editing the server.xml file directly but I thought you should know that the instructions on this page appear to be inaccurate.

    1. Hi,

      The instructions on this page are for the 5.2 EAP. The JIRA Config tool does not have the other Web Server fields in JIRA 5.1 and earlier. Please see these JIRA 5.1 instructions instead.

      Kind Regards,
      Andrew

      1. Anonymous

        Thank you Andrew.

         

  28. Anonymous

    Hi,

    This might be a very silly question but I don't know:

    if I have JIRA running over IIS (IIS 8 windows server 2012 essentials) with JIRA running on the same server and I can only reach the server via HTTPS (port 80 is used for a different application) is than my complete connection secure? Or should I still follow the above process?

    Kind regards,

    Steven

     

  29. Can we use any other alias name other than 'tomcat' ??

    1. You can, it depends on what is the alias name that you gave while inserting the certificate into the keystore. The default is tomcat.

  30. keytool -list -v -keyfile $JIRA_INST/conf/cacert and I am able to view all the contents of my kesytore

    but when I am trying to import using config.sh

    Please select the keystore from the options below. It must contain the certificate and the private key to be used.
    [S] The system-wide Java keystore (/cust/soe/opt/jdk/1.6.0-19/jre/lib/security/cacerts)
    [U] User-defined location
    Keystore> U
    Keystore Path (leave blank to exit)> /cust/atlassian/jira_app1/conf/cacerts
    Keystore Password>
    Key Alias> tomcat
    The referenced certificate could not be found or accessed. Do you want to try again? ([Y]/N)? > N

    Can you please let me know hw to proceed further ?

    1. Can you please raise this query at Atlassian  Answers please?  Link at the end of this page.

    2. Thank you , I have fixed it myself....While running the commands here keytool -import -alias [your_alias_name] -trustcacerts -file X.509_file_name -keystore [keystorename]

      keystorename should be the JKS which you have provided before submitting to your CA, whereas I pointed that to new keystore.

  31. I've been struggling to tell JIRA to use a .crt file I've got from GoDaddy. You would think things would have been sorted out after 2 years, but no..

    Got pretty much all the errors in the book, whereas the whole installation with another apache server took seconds.

    My sincere question is, why is this so difficult? Why can't we just point to the new key in JIRA admin screen and the background would take care of things?

  32. I just managed to get a wildcard certificate installed for JIRA, and it seems to be working fine, with one caveat. Most of our users access JIRA at hostname:8088 (which redirects now to hostname:8443). When this happens, they get a certificate error. When they use hostname.domain.org:8088, no error. I know this is probably something really stupid, but it's been driving me crazy trying to search for an answer online. Can anyone help with this? 

    Server is win2k8, JIRA is 6.0.2, and cert is a CA wildcard cert for our domain which was imported from another server it was installed on (as PFX) and then converted to JKS using keytool. I used the config.bat tool to add it, and that gave no errors.  

  33. Seems to be a bug here in the config tool (and your docn). The patterns set up when the auto-config tool configures SSL do not include REST, eg the following url is not redirected to https: <host>://<context>/rest/greenhopper/1.0/rapidviews/list

    Seems like you want want these to be, as you could be passing authentication information here.

  34. Anonymous

    I used the command line install and it didn't work.  After pulling my hair out and searching around, I realized that the command line instructions for installing the signed certificate are incorrect.  In order to install the "Reply" correctly, you must use the command line argument -trustcacerts with the:

    <JAVA_HOME>/keytool -import -alias jira -keystore <JIRA_INSTALL>/jira.jks -file jira.crt
    command shown in the command line instructions.
    That line was incorrect for my version of JIRA, without the -trustcacerts argument.
    Hope this help someone,
    Jeff Kirk
  35. what a nightmare, could it be more ridiculous?  anyway, here are the steps I had to use for an existing cert

    1. Export PFX file from Windows Server
      1. Start MMC
      2. Add certificate snap-in, run as local computer
      3. Expand personal store, select the cert, right click export
      4. Check the option to Include all certificates in the certification path if possible
      5. and do NOT check the options to Enable strong protection and to Delete the private key if the export is successful
      6. make the password for the export - password .  This is important later on when making this into a jks store.

     

    1. Use OpenSSL Version 1.01e to extract the certificate  - http://slproweb.com/products/Win32OpenSSL.html -   version .98 has a bug that directly affects step e.
      1. Taken partially from digicert - http://www.digicert.com/ssl-support/jks-import-export-java.htm
      2. b.      openssl pkcs12 -in yourfilename.pfx -out tempcertfile.crt -nodes
      3. c.       open tempcertfile.crt and CUT the Private key into another file like tempcertfile.key, private key includes the lines  ---- begin rsa private key ----, ----end rsa private key----
      4. d.      delete any lines in the tempcertfile.crt that arent in-between --- begin xxx ---, ---end xxx--- and save it.

     

    1. 3.       Recombine the files into a PKCS12 file (Technically the PFX file exported originally is already a pkcs12 file, but Jira does not like it.)
      1. a.  openssl pkcs12 -export -in tempcertfile.crt -inkey tempcertfile.key -name jira -out jira.p12
      2. b.  Important, -name will be the alias Jira uses to search the cert,  I used "jira" for the -name, but it can be anything.

     

    1. 4.       Use Portecle - http://sourceforge.net/projects/portecle/ - to convert the jira.12 file into a jks store
      1. Probably need to update java - search for "java unlimited strength security files" - download them and overwrite the existing files- "c:\Program Files\Java\jre7\lib\security"
      2. Start portecle from the command prompt  -  "c:\program files\java\jre7\bin\java" -jar "c:\program files\portecle\portecle.jar"
      3. Under the file menu, import in jira.p12. Under tools menu, convert it to a jks store.  Portecle warns about a keypair during conversion and setting the password on the keypair to password. This is ok if you followed exported the pfx with password.
      4. Save the converted jks store to somewhere like the <jira install directory>\jira.jks.

     

    1. Stop Jira and Run config.bat in your <jira install path>\bin and click the "web server" tab
      1.  screen shot  the settings and backup your <jira install>\conf\server.xml file so you can easily return to the previous state.
      2. Fill out the lines appropriately.  -- > see https://confluence.atlassian.com/display/JIRA/Running+JIRA+over+SSL+or+HTTPS for additional help.
      3. If you followed this example, keystorepath = <jira install directory>\jira.jks; keystore password is password; and alias is jira.
      4. IF the button, Check Certificate in the Key Store,  at the bottom fails,  Jira SSL will fail.  Try to fix any errors it tells you.  Using these instruction, it should not fail. But if it does, you need to address whatever it complains about.
      5. Start Jira
      6. IF there are problems with Jira functioning properly, check the catalina logs under <jira install directory>/logs for clues.
  36. Two cents for the Portecle section:

    1. If you are new with Linux, you can run Portecle with the command:
      # java -jar ./protecle.jar
    2. You do not need to change the JAVA_HOME var to use , Portecle has an option to use an explicit JRE.
      Run the tool and use the "Tools - Option - CA Certs Keystore", and browse for the Jira JRE cert file (jre/lib/security/cacerts) and follow on as indicated in the instructions (you did not have to change your JAVA_HOME value).
  37. Anonymous

    the command is genkeypair in place genkey

      keytool -genkeypair -alias jira -keyalg RSA -keystore <JIRA_INSTALL>/jira.jks

  38. Hi.

    Can you help?

    When a Self-signed certificate is used, how it should matter?
    The downside is that all commands that display sample is using a. Crt. Instead the Self-signed certificate is. Csr

    1. A csr is a certificate signing request, you have not finished creating your self signed cert yet.

  39. Hi.

    Then. How I generated a Self-signed certificate?. jira to run on ssl.

    We use this guide: https://confluence.atlassian.com/display/JIRA/Running+JIRA+over+SSL+or+HTTPS.

    1.Generate the Java KeyStore
    2. Generate the .csr
    3.Configuring your web server using the JIRA configuration tool

    We doubt if all we have to do?. How to generate the Self-signed certificate?

    Right now we can access using Jira https://smart-atlassian:8443

  40. Hi all.

    I had quite the struggle while installing a GoDaddy certificate using command line. It kept telling me that the chain was incorrect when I was importing the main cert. After a while of trial and error, with very little help from the internet, I figured it out. Godaddy doesn't include the main root certificate in the downloadable zip files, just the cert and intermediate CA. 

    In order to get the main cert to install I had to install (step 5 in command line guide) the "Go Daddy Class 2 Certification Authority Root Certificate - G2" from their repository (https://certs.godaddy.com/anonymous/repository.pki)

    I hope this helps anyone that has the same problem I had.

  41. Should <JIRA_INSTALL>/WEB-INF/web.xml in the advanced configuration section above be <JIRA_INSTALL>/conf/web.xml (Jira 6.2.5)?