Integrating JIRA with Apache using SSL

Atlassian applications allow the use of reverse-proxies within our products, however Atlassian Support does not provide assistance for configuring them. Consequently, Atlassian can not guarantee providing any support for them.

If assistance with configuration is required, please raise a question on Atlassian Answers.

This page describes how to integrate Apache HTTP Server (also referred to as httpd) with JIRA, utilizing mod_proxy & mod_ssl so that Apache operates as a reverse-proxy over HTTPS. If a HTTP configuration is required, please see our Integrating JIRA with Apache documentation. Configuring Apache allows for running JIRA on non-standard HTTP port (such as 8080) and users will be able to access JIRA over standard HTTPS as their traffic will be routed through the proxy and encrypted outside of the network.

Apache can be configured to allow access to JIRA in any of the following methods:

Directly on its own domain: https://atlassian.com/
As a subdomain of another domain: https://jira.atlassian.com
It can also be accessed on a context path on either a domain or subdomain: https://atlassian.com/jira

This means the SSL certificate will be managed within Apache and not Tomcat, additionally the connection between Apache and Tomcat will not be encrypted. However, the connection between the browser and the outside network will be encrypted. This is suitable for configurations where the JIRA server is within the same network as the Apache server and is illustrated below:

Client Browser -> HTTPS -> Apache Proxy -> HTTP -> Tomcat (JIRA)

On this page:

This is a common configuration for networks with multiple SSL certificates and/or web applications as they are all managed in one location (Apache).

If a more complicated solution is required, refer to the Apache HTTP Server Version Documentation, consult with the Apache SME within your organization, and if need be, raise a question on Atlassian Answers, or get in touch with one of our Atlassian Experts.

Expand for an example of a common Apache configuration

JIRA is running on port 8080 on a server within the LAN that cannot be accessed externally (the router/firewall is not forwarding port 8080 to it).
Apache is set up on another server (or the same server as JIRA) that can be accessed externally on HTTPS (443).
Apache is then accessed over HTTPS on the appropriate URL (VirtualHost), routing the traffic to and from the JIRA server.

Before you begin

It is expected that the SSL certificate has been signed by a CA and is in the PEM format prior to configuring Apache. For assistance preparing and generating SSL certificates, please consult with a SSL Vendor (for example, GoDaddy, Verisign, RapidSSL).

Identifying whether to use a domain, subdomain or context path largely depends on the type of SSL certificate provided and also any business rules around website configurations. For SSL to function without error, the domain must match the Common Name (CN) of the certificate.

Expand for further information on configuring the FQDN to match the certificate's CN

This table indicates which URLs will work with the certificate CN and also makes a recommendation on the URL to use.

JIRA FQDN	Common Name	Recommend JIRA FQDN
https://jira.atlassian.com	`jira.atlassian.com`	https://jira.atlassian.com
https://jira.atlassian.com	`*.atlassian.com`	https://jira.atlassian.com
https://jira.atlassian.com	`atlassian.com`	https://atlassian.com/jira
https://atlassian.com	`atlassian.com`	https://atlassian.com/jira
https://atlassian.com	`jira.atlassian.com`	https://jira.atlassian.com

A certificate that has a CN with an asterisk (*) in it is a wildcard certificate and can support any subdomain of that domain. If you are uncertain about the URL to use, please consult with your System Administrator and the SSL vendor that provided the certificate.

Step 1: Configure Tomcat

Stop JIRA.

(Optional: If JIRA does not require a context path, skip this step.)

Edit Tomcat's server.xml to include the required JIRA context path. The below example uses path="jira" - this means JIRA is accessible on http://jiraserver:8080/jira given the default JIRA port is used.

        <Engine defaultHost="localhost" name="Catalina">
            <Host appBase="webapps" autoDeploy="true" name="localhost" unpackWARs="true">
                <Context docBase="${catalina.home}/atlassian-jira" path="/jira" reloadable="false" useHttpOnly="true">

                    <!--
                     ====================================================================================
                     Note, you no longer configure your database driver or connection parameters here.
                     These are configured through the UI during application setup.
                     ====================================================================================
                    -->
                    <Resource auth="Container" factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60" name="UserTransaction" type="javax.transaction.UserTransaction"/>
                    <Manager pathname=""/>
                </Context>
            </Host>

Ensure the path value is set with a prepending forward slash (/) . For example, path="/jira" rather than path="jira".

Edit Tomcat's server.xml to include a separate connector to proxy the requests. This requires the scheme, proxyName & proxyPort attributes. Replace them with the appropriate domain and port of the proxy, as in the below example:

<Service name="Catalina">
 
	<!-- Apache Proxy Connector with values for scheme, proxyName and proxyPort -->
        <Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" port="8080" protocol="HTTP/1.1" redirectPort="8443" useBodyEncodingForURI="true" 
            scheme="https" proxyName="jira.atlassian.com" proxyPort="443"/> 

	<!-- Standard HTTP Connector -->
        <Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" port="8081" protocol="HTTP/1.1" redirectPort="8443" useBodyEncodingForURI="true"/>

Disable any redirections within Tomcat to HTTPS if they have been enabled - for example the changes to WEB-INF/web.xml in Running JIRA applications over SSL or HTTPS will cause errors when using Apache.
Start JIRA.
Test that JIRA is accessible on the normal connector, using a context path if applicable - for example http://jiraserver:8081/jira.
Test that the new connector is in effect by accessing JIRA on the appropriate proxy connector. The behavior varies depending on the context path:
1. If the context path is empty or root (/), visiting JIRA via the proxy connector (e.g. http://jiraserver:8080/) should take you to JIRA with a warning:
2. If the context path is other than empty or root (/), e.g. /jira , visiting JIRA via the proxy connector (e.g. http://jiraserver:8080/jira) should redirect you to the configured proxy (e.g. https://jira.atlassian.com/jira).

We use two different Tomcat connectors so that testing can be done on JIRA, bypassing the proxy when needed as this is a useful step when troubleshooting. It is expected that the standard connector will not be allowed external access from outside the network (the firewall will not forward any ports to it).

Step 2: Configure Apache HTTP Server

The installation of Apache and configuration of a DNS is not covered in this documentation. Additionally, it is assumed that Apache 2.2 has been installed and DNS entries have been configured for the JIRA domain. As Apache's configuration is specific to the operation system that is used, only some distributions and their configurations are currently documented.

2.1 Enable the Proxy Modules

Debian/Ubuntu

Expand to see Debian/Ubuntu instructions

Enable the module with the following:

$ sudo a2enmod proxy_http ssl
Considering dependency proxy for proxy_http:
Enabling module proxy.
Enabling module proxy_http.
Enabling module ssl.
See /usr/share/doc/apache2.2-common/README.Debian.gz on how to configure SSL and create self-signed certificates.
To activate the new configuration, you need to run:
  service apache2 restart

Restart Apache.

Windows/Other OS

Expand to see Windows/Other OS instructions

Locate and edit the httpd.conf file, adding the below lines if they do not already exist:

LoadModule proxy_module modules/mod_proxy.so 
LoadModule proxy_connect_module modules/mod_proxy_connect.so 
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule ssl_module modules/mod_ssl.so

Restart Apache.

2.2. Configure Apache to use those Modules

Debian/Ubuntu

Expand to see Debian/Ubuntu instructions

Switch into user root.
Backup the existing instance or create a new one. Creating a new instance is not covered within this documentation (copying the default should be sufficient).
Modify the existing instance within $APACHE_INSTALL/sites-available, for example default-ssl.

Add the following inside the VirtualHost, replacing jiraserver with the hostname of the JIRA server and also modifying the port if required.

On its own domain or subdomain:

# JIRA Proxy Configuration:
<Proxy *>
        Order deny,allow
        Allow from all
</Proxy>

SSLProxyEngine          On
ProxyRequests           Off
ProxyPreserveHost       On
ProxyPass               /       http://jiraserver:8080/
ProxyPassReverse        /       http://jiraserver:8080/

Missing a forward slash at the end of the URL will cause proxy errors - ensure this is in place!

Using a context path:

# JIRA Proxy Configuration:
<Proxy *>
        Order deny,allow
        Allow from all
</Proxy>

SSLProxyEngine          On
ProxyRequests           Off
ProxyPreserveHost       On
ProxyPass               /jira       http://jiraserver:8080/jira
ProxyPassReverse        /jira       http://jiraserver:8080/jira

The path used must be identical to the Tomcat context path. For example, forwarding /jira to /jira520 cannot be done without considerable rewrite rules that are not always reliable.

Enable the instance with the following:

# a2ensite default-ssl
Enabling site default-ssl.
To activate the new configuration, you need to run:
  service apache2 reload

Copy the certificate and private key to the appropriate directories.

Include them in the Apache configuration, within the VirtualHost as below:

SSLCertificateFile    /etc/ssl/certs/jira.crt
SSLCertificateKeyFile /etc/ssl/private/jira.key

(OPTIONAL): Configuration of SSLCertificateChainFile will contain the intermediate certificates provided by the CA vendor who signed it. Please follow consult with the CA vendor to verify if this is required.
```
SSLCertificateChainFile /etc/ssl/certs/jiraintermediate.crt
```
Reload the Apache configuration.
Test by accessing JIRA through Apache, for example http://jira.com or http://atlassian.com/jira.

Windows/Other OS

Expand to see Windows/Other OS instructions

Locate and edit the httpd.conf file.

Add the following inside the VirtualHost, replacing jiraserver with the hostname of the JIRA server and also modifying the port if required.

On its own domain or subdomain:

# JIRA Proxy Configuration:
<Proxy *>
        Order deny,allow
        Allow from all
</Proxy>

SSLProxyEngine          On
ProxyRequests           Off
ProxyPreserveHost       On
ProxyPass               /       http://jiraserver:8080/
ProxyPassReverse        /       http://jiraserver:8080/

Missing a forward slash at the end of the URL will cause proxy errors - ensure this is in place!

Using a context path:

# JIRA Proxy Configuration:
<Proxy *>
        Order deny,allow
        Allow from all
</Proxy>

SSLProxyEngine          On
ProxyRequests           Off
ProxyPreserveHost       On
ProxyPass               /jira       http://jiraserver:8080/jira
ProxyPassReverse        /jira       http://jiraserver:8080/jira

The path used must be identical to the Tomcat context path. For example, forwarding /jira to /jira520 cannot be done without considerable rewrite rules that are not always reliable.

Copy the certificate and private key to the appropriate directories.

Include them in the Apache configuration, within the VirtualHost as below:

SSLCertificateFile      /etc/ssl/certs/jira.crt
SSLCertificateKeyFile   /etc/ssl/private/jira.key

(OPTIONAL): Configuration of SSLCertificateChainFile will contain the intermediate certificates provided by the CA vendor who signed it. Please follow consult with the CA vendor to verify if this is required.
```
SSLCertificateChainFile /etc/ssl/certs/jiraintermediate.crt
```
Restart Apache.
Test by accessing JIRA through Apache, for example http://jira.com or http://atlassian.com/jira.

2.3 Redirect HTTP to HTTPS

This can be done with either of the following:

Set up the HTTP VirtualHost to forward to the same Tomcat Connector. Tomcat will redirect to HTTPS using the scheme, proxyName & proxyPort parameters. This can be done as in our Integrating JIRA with Apache documentation.
Using mod_rewrite (this module may require enabling), add the following to the HTTP VirtualHost:
```
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
```

Step 3: Configure JIRA

Set Use gzip compression to OFF as in Configuring JIRA options. GZIP compression is known to cause performance issues using a reverse-proxy, especially if the proxy is also compressing the traffic.
Set the Base URL to be the FQDN that JIRA will be accessed on, for example https://jira.atlassian.com. This is also located in Configuring JIRA options.
JIRA can only be configured to respond to a single URL and the Base URL (as in Configuring JIRA options) must match the URL end-users are accessing. Misconfiguration of this may cause significant problems within JIRA such as the Activity Stream and Dashboard Gadgets failing to function correctly.
Test by accessing JIRA on the FQDN (e.g.: https://jira.atlassian.com), ensuring that JIRA is accessible and all dashboard gadgets correctly display.

Troubleshooting

Hijacked Sessions: Some users have reported problems with user sessions being hijacked when the mod_cache module is enabled. If these problems are encountered, try disabling the mod_cache module.
This module is enabled by default in some Apache HTTP Server version 2 distributions.
Permission Denied Errors enabling mod_proxy (and mod_jk) on Linux distros that use SELinux: Users have reported 'permission denied' errors when trying to get mod_proxy (and mod_jk) working. Disabling SELinux (/etc/selinux/config) apparently fixes this.
Running Mac OS X: Disable webperfcache, which proxies port 80 by default. A user reported this as the likely cause of JIRA session problems, in the form of users' identities becoming mixed up, as below.
Additionally we do not recommend using Max OS X as it is not supported, as in our Supported platforms.

The OSX Servers enable webperfcache by default for Virtual Hosts, which for static content would be great, but for dynamic instances (which ALL of ours are) it is Evil and causes many issues.
Of note recently was the jira session issue. Also see :-
http://developer.apple.com/documentation/Darwin/Reference/ManPages/man8/webperfcache.8.html
Unfortunately even if you disable webperfcache for a instance, if there is a single instance enabled then all instances will still proxy through webperfcache with resulting session problems.

Too many redirects: Both Tomcat & Apache are redirecting, when only one should be. Disable redirection in Tomcat (revert any changes as in Running JIRA over SSL or HTTPS) and check that there is only one redirection in Apache.
General Problems:
1. Clear the browser cache and try again.
2. Ensure that JIRA works as expected when running directly from Tomcat and bypassing Apache. For example, accessing http://jiraserver:8080 instead of http://jira.atlassian.com.
3. Increase the LogLevel for Apache to debug and restart it.
4. Attempt to access JIRA and check the Apache Log Files for any errors.
5. Raise a question on Atlassian Answers for assistance.

403 Forbidden error:

Add the RequestHeader unset Authorization line to the apache configuration page to disable authorization headers.

<Location /jira>
  RequestHeader unset Authorization
  ProxyPreserveHost On
  ProxyPass http://jiraserver/jira
  ProxyPassReverse http://jiraserver/jira
</Location>

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

System Status

Suggestions and bugs

Marketplace

Billing and licensing

Integrating JIRA with Apache using SSL

Integrating JIRA with Apache

On this page

Still need help?

Before you begin

Step 1: Configure Tomcat

Step 2: Configure Apache HTTP Server

2.1 Enable the Proxy Modules

Debian/Ubuntu

Windows/Other OS

2.2. Configure Apache to use those Modules

Debian/Ubuntu

On its own domain or subdomain:

Using a context path:

Windows/Other OS

2.3 Redirect HTTP to HTTPS

Step 3: Configure JIRA

Troubleshooting

See Also

Page

Viewport

Confluence

Integrating JIRA with Apache using SSL

Integrating JIRA with Apache

On this page

Related content

Still need help?

Before you begin

Step 1: Configure Tomcat

Step 2: Configure Apache HTTP Server

2.1 Enable the Proxy Modules

Debian/Ubuntu

Windows/Other OS

2.2. Configure Apache to use those Modules

Debian/Ubuntu

On its own domain or subdomain:

Using a context path:

Windows/Other OS

2.3 Redirect HTTP to HTTPS

Step 3: Configure JIRA

Troubleshooting

See Also

Related content