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 Community.
“Ghostcat” vulnerability in Apache Tomcat
Following this guide might make your Jira instance prone to a recent high-risk vulnerability found in Apache Tomcat.
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.
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.
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 usespath="jira"
- this means Jira is accessible onhttp://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 thanpath="jira"
.Edit Tomcat's
server.xml
to include a separate connector to proxy the requests. This requires thescheme
,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" relaxedQueryChars="[]|{}^c;`"<>" 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:
- 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: - 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
).
- If the context path is empty or root (
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
Windows/Other OS
2.2. Configure Apache to use those Modules
Debian/Ubuntu
Windows/Other OS
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 thescheme
,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
(andmod_jk
) on Linux distros that use SELinux: Users have reported 'permission denied' errors when trying to getmod_proxy
(andmod_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:
- Clear the browser cache and try again.
- 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. - Increase the LogLevel for Apache to debug and restart it.
- Attempt to access Jira and check the Apache Log Files for any errors.
- 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>
See Also
- Integrating Jira with Apache
- Configuring Apache Reverse Proxy Using the AJP Protocol
- For more advanced
mod_webapp
configurations (eg. SSL), see this mod_proxy guide. - Apache Virtual Host documentation