Integrating JIRA with Apache using SSL

The content on this page relates to platforms which are not supported by JIRA. Consequently, Atlassian can not guarantee providing any support for it. Please be aware that this material is provided for your information only and using it is done so at your own risk.

This page describes using an SSL connection between Apache and Tomcat, which is not a common configuration. This connection is usually unnecessary as it's behind the firewall and the SSL connection can terminate on Apache, and use an HTTP to connect to Tomcat. For information on integrating JIRA with Apache without SSL, use the Integrating JIRA with Apache documentation. For the specific configuration of terminating the SSL connection at Apache, find the "Terminating an SSL connection at Apache" section.

If you want to use https (e.g. https://mycompany.com/jira/), then:

Step 1. In Apache, ensure SSLProxyEngine is on

In the Apache config (/etc/apache2/sites-available/jira-mod_proxy), ensure you have SSLProxyEngine on specified, and redirect /jira to https://localhost:8443/jira:

<Proxy *>
Order deny,allow
Allow from all
</Proxy>

SSLProxyEngine on
ProxyRequests       Off
ProxyPreserveHost On
ProxyPass           /jira       https://localhost:8443/jira
ProxyPassReverse    /jira       https://localhost:8443/jira

Please ensure that the ProxyPass and ProxyPassReverse directives do not include a trailing '/'. There have been reports that this may cause problems in JIRA 3.7 and above when serving static resources (javascript and css).

Step 2. Configure Tomcat to use SSL (JIRA Standalone)

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

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

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).

Step 3. Import Apache's public SSL key into Tomcat's keystore

Obtain the server's public key:

To quote Microsoft; "consult your system administrator". The public/private key pair will live somewhere on the server. The public key should be located and copied to the server hosting JIRA/Confluence. For example:

scp root@mail.yourcompany.com:/etc/ssl/certs/httpd.pem .

If you have openssl installed locally, the key can be retrieved with a command like:

donna-mcgahans-macbook-pro:~ dmcgahan$ openssl s_client -connect support.atlassian.com:https
CONNECTED(00000003)
depth=1 /C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global CA
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
 0 s:/C=au/ST=NSW/L=Sydney/O=ATLASSIAN SOFTWARE SYSTEMS PROPRIETARY LIMITED/OU=IT/CN=*.atlassian.com
   i:/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global CA
 1 s:/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global CA
   i:/C=US/O=Entrust.net/OU=www.entrust.net/CPS incorp. by ref. (limits liab.)/OU=(c) 1999 Entrust.net Limited/CN=Entrust.net Secure Server Certification Authority
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIGYDCCBUigAwIBAgIQCi1wR9xdR7qYjJaF4e+4YDANBgkqhkiG9w0BAQUFADBc
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMRswGQYDVQQDExJEaWdpQ2VydCBHbG9iYWwgQ0EwHhcN
MDgwMTEwMDAwMDAwWhcNMTEwMTEzMjM1OTU5WjCBjDELMAkGA1UEBhMCYXUxDDAK
BgNVBAgTA05TVzEPMA0GA1UEBxMGU3lkbmV5MTcwNQYDVQQKEy5BVExBU1NJQU4g
U09GVFdBUkUgU1lTVEVNUyBQUk9QUklFVEFSWSBMSU1JVEVEMQswCQYDVQQLEwJJ
VDEYMBYGA1UEAxQPKi5hdGxhc3NpYW4uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GN
ADCBiQKBgQDKjT2WNJaRLC2q/QEndjdVtriS/qMQfeX+sXgz4tSN+jd1zupOzuDo
xUfTilVLIt8aR5/bSa+XY3ykj5RcNRxki7Q/rr30FANY3cKCxY2TYZjVoPYVipnW
VDubtpjvUywE6E5LwI33oFqqnhL+HzEOioXOBHdU2/tZHj8n0VR7hQIDAQABo4ID
bzCCA2swHwYDVR0jBBgwFoAUp8cToHoBPJ3vgkiCSNVzUbYSViowHQYDVR0OBBYE
FOibDc5A2xBHAf8MBqnaEFQJswQBMCkGA1UdEQQiMCCCDyouYXRsYXNzaWFuLmNv
bYINYXRsYXNzaWFuLmNvbTB2BggrBgEFBQcBAQRqMGgwJAYIKwYBBQUHMAGGGGh0
dHA6Ly9vY3NwLmRpZ2ljZXJ0LmNvbTBABggrBgEFBQcwAoY0aHR0cDovL3d3dy5k
aWdpY2VydC5jb20vQ0FDZXJ0cy9EaWdpQ2VydEdsb2JhbENBLmNydDAOBgNVHQ8B
Af8EBAMCBaAwDAYDVR0TAQH/BAIwADB/BgNVHR8EeDB2MDmgN6A1hjNodHRwOi8v
Y3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRHbG9iYWxDQS0yMDA4YS5jcmwwOaA3
oDWGM2h0dHA6Ly9jcmw0LmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydEdsb2JhbENBLTIw
MDhhLmNybDCCAcYGA1UdIASCAb0wggG5MIIBtQYLYIZIAYb9bAEDAAEwggGkMDoG
CCsGAQUFBwIBFi5odHRwOi8vd3d3LmRpZ2ljZXJ0LmNvbS9zc2wtY3BzLXJlcG9z
aXRvcnkuaHRtMIIBZAYIKwYBBQUHAgIwggFWHoIBUgBBAG4AeQAgAHUAcwBlACAA
bwBmACAAdABoAGkAcwAgAEMAZQByAHQAaQBmAGkAYwBhAHQAZQAgAGMAbwBuAHMA
dABpAHQAdQB0AGUAcwAgAGEAYwBjAGUAcAB0AGEAbgBjAGUAIABvAGYAIAB0AGgA
ZQAgAEQAaQBnAGkAQwBlAHIAdAAgAEMAUAAvAEMAUABTACAAYQBuAGQAIAB0AGgA
ZQAgAFIAZQBsAHkAaQBuAGcAIABQAGEAcgB0AHkAIABBAGcAcgBlAGUAbQBlAG4A
dAAgAHcAaABpAGMAaAAgAGwAaQBtAGkAdAAgAGwAaQBhAGIAaQBsAGkAdAB5ACAA
YQBuAGQAIABhAHIAZQAgAGkAbgBjAG8AcgBwAG8AcgBhAHQAZQBkACAAaABlAHIA
ZQBpAG4AIABiAHkAIAByAGUAZgBlAHIAZQBuAGMAZQAuMB0GA1UdJQQWMBQGCCsG
AQUFBwMBBggrBgEFBQcDAjANBgkqhkiG9w0BAQUFAAOCAQEAspPrcCoRqI94BaPB
vujILnWqhnAjGp9QAI08YKNtAXp6X65Ytl48f3VOLivqCwVesm7FM7lXpFf46Kbj
9kfii/003x8+0rJo34lJcTIPO0EEu1tbvHKDcueII16g8Sfnpm9xZNi8imVunB6K
r9ID9Bl+ROl3u9wf6JgYIVeMxMD8lGKqCckjOimErIuB3Ca/A+L6+8eAp0/Y0yyE
z7cCI7kllKdjTvu5Y/GoN/cyBYKv57LeUrrNr7uMuyk0TJq0bFUl4KRMY6u3Rihe
zYNouvdneLKqlOwk4tBPODGm6LN0ubQc9C3J4pkrHhzEGXsEnk21O9syQ7ym9/1B
5++R3Q==
-----END CERTIFICATE-----

Cut and paste the certificate (including BEGIN and END lines) into a local file (eg. httpd.pem).

Import the public key

To do this, you need to use the keytool program that comes with Java. If you haven't already, add $JAVA_HOME/bin to your PATH, and then run the following:

jturner@teacup:~$ sudo keytool -import -alias mail.yourcompany.com -keystore $JAVA_HOME/jre/lib/security/cacerts -file imapd.pem
Enter keystore password:  changeit
Owner: EMAILADDRESS=info@atlassian.com, CN=atlassian.com, O=Atlassian, L=Sydney, ST=NSW, C=AU
Issuer: EMAILADDRESS=info@atlassian.com, CN=atlassian.com, O=Atlassian, L=Sydney, ST=NSW, C=AU
Serial number: 0
Valid from: Fri Feb 11 14:09:05 EST 2005 until: Sat Feb 11 14:09:05 EST 2006
Certificate fingerprints:
MD5:  CB:AE:7D:5D:1A:08:06:77:93:3B:0F:53:BB:40:C0:D4
SHA1: 7C:02:44:0D:A9:8F:F9:FB:BB:7B:C6:F1:52:DE:CA:00:17:D9:3A:A0
Trust this certificate? [no]:  yes
Certificate was added to keystore

This will import the public key (imapd.pem) into Java's default keystore, and marks it as trusted.

On Windows the command is similar, eg.:

C:\Program Files\Java\jre1.6.0_05>bin\keytool -import -file c:\certs\imapd.pem -alias mail.yourcompany.com -keystore lib\security\cacerts
Enter keystore password:
Owner: CN=*.atlassian.com, OU=IT, O=ATLASSIAN SOFTWARE SYSTEMS PROPRIETARY LIMITED, L=Sydney, ST=NSW, C=au
Issuer: CN=DigiCert Global CA, OU=www.digicert.com, O=DigiCert Inc, C=US
Serial number: a2d7047dc5d47ba988c9685e1efb860
Valid from: Thu Jan 10 11:00:00 EST 2008 until: Fri Jan 14 10:59:59 EST 2011
Certificate fingerprints:
         MD5:  9D:B4:9F:3D:0A:DE:6A:BD:BC:3D:95:BE:60:BD:70:02
         SHA1: 67:C6:E9:C8:3F:F1:7A:3C:66:E2:CE:62:78:A1:66:84:35:5E:62:1E
         Signature algorithm name: SHA1withRSA
         Version: 3
.....

Trust this certificate? [no]:  yes
Certificate was added to keystore

C:\Program Files\Java\jre1.6.0_05>

Step 4. Restart the app server

Restart, and if everything is correct, your webapp should now connect to the SSL resource without problems.

Note: Alternative keystore locations

Java will normally use a system-wide keystore in $JAVA_HOME/jre/lib/security/cacerts, but it is possible to use a different keystore by specifying a parameter, -Djavax.net.ssl.trustStore=/path/to/keystore, where '/path/to/keystore' is the absolute file path of the alternative keystore.

Setting this is not recommended, however, because if Java is told to use a custom keystore (eg. containing a self-signed certificate), then Java will not have access to the root certificates of signing authorities found in $JAVA_HOME/jre/lib/security/cacerts, and accessing most CA-signed SSL sites will fail. It is better to add new certificates (eg. self-signed) to the system-wide keystore (as above).

There is also a per-user truststore (~/.keystore) but (at least on Linux), but its contents do not appear to be logically appended to those in the system-wide keystore; ie. it is entirely separate, and only used if one specifies -Djavax.net.ssl.trustStore=/home/<user>/.keystore. This has the same disadvantage described above with custom keystores, so the per-user truststore is best avoided.

Note: Alternative configuration if HTTPS is terminated on the proxy server

If HTTPS is terminated on the proxy server, i.e.:

    Client Browser --> HTTPS --> Apache proxy --> HTTP --> Tomcat/JIRA

then you will need to configure steps 1 and 2 slightly differently.

Specifically a HTTP Connector needs to be defined (identical to the default 8080 Connector) with the addition of the following attributes: scheme="https", proxyName="<proxy_server>", proxyPort="<proxy_port>"

Default connector:

<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               URIEncoding="UTF-8"
               useBodyEncodingForURI="true"
 />

Connector that supports HTTPS terminated on the proxy server:

<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               URIEncoding="UTF-8"
               useBodyEncodingForURI="true"
              
               <!-- The below are new lines to add - the above is untouched -->
               scheme="https"
               proxyName="<proxy_server>"
               proxyPort="443"
 />

In this scenario, the Apache httpd.conf file needs to be modified from:

ProxyPass              /jira       https://localhost:8443/jira
ProxyPassReverse       /jira       https://localhost:8443/jira

to

ProxyPass              /jira       http://localhost:8080/jira
ProxyPassReverse       /jira       http://localhost:8080/jira

(Note the changes to the scheme and port).

Child pages