TECHNICAL BRIEF How to Set Up JIRA to Work Behind an Apache Proxy and Use SSL By Sylvia Ganovska Linux Engineer Overview As most people reading this business brief will know, separating the web/presentation layer from the underlying application is generally considered to be a best practice and is certainly one that Coyote Creek follows. The reasons to do this include better security, clear and more manageable application configuration and a more logical network layout via separation of functional servers. JIRA, by default, runs on port 8080. If you want to run JIRA over SSL, the most appropriate way to accomplish this is by using a proxy server such as Apache. Apache can be configured in both a forward and reverse proxy mode. A forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the JIRA server, the client sends a request to the proxy naming the JIRA server as the target; the proxy then requests the content from the JIRA server and returns it to the client. The forward proxy is activated using the ProxyRequests directive. A reverse proxy, by contrast, appears to the client just like an ordinary web server; no special configuration on the client is necessary. A typical usage of a reverse proxy is to provide Internet users access to a server that is behind a firewall. The Goal To set up JIRA to work behind an Apache proxy and use SSL. Here are the steps to make this happen: Step 1: Change JIRA’s base URL 1. Login to JIRA as an administrator. 2. Go to the administration page. 3. From the main menu select “System”> “General Configuration”. 4.Select “Edit Configuration” and then set Base URL to https://YourDomain/jira 5.Select “Update”. Step 2: Create a self-signed SSL certificate for Apache Self-signed SSL certificates are useful in cases where you require encryption but do not need to verify the website identity. They are commonly used for testing purposes and on internal corporate networks (i.e. intranets). 1. First create your new private key (privkey.pem) and server.csr: openssl req -config /etc/pki/tls/openssl.cnf -new -out server.csr Assumptions • You have a working http instance of JIRA on port 8080 It will ask you for a PEM pass phrase. Enter a pass phrase, confirm it and remember it! Then it will ask you for some extra information. The most important item here is to set the “Common Name” (e.g., your name or your server’s hostname) exactly as your hostname (FQDN). This creates a server.pem file. • You have a running Apache server with an enabled mod_ proxy module 2. Create the server.key file: openssl rsa -in privkey.pem -out server.key • Firewall is properly configured to permit connections on port 443 1 tel 1.888.269.6838 coyotecrk.com It will ask you for the privkey.pem (“Enter pass phrase for privkey.pem”). You must enter the pass phrase you chose in 1. TECHNICAL BRIEF 3. Create the server.crt using the key you have just generated: openssl x509 -in server.csr -out server.crt -req -signkey server.key -days 365 (note: This server key will be good for 365 days) As a result of the above 3 steps you will have 4 files. Check them with the “ls –l” command. ls -l -rw-r--r--rw-r--r--rw-r--r--rw-r--r-- 1 root root 1 root root 1 root root 1 root root 1834 Jun 26 11:28 privkey.pem 1273 Jun 26 11:30 server.crt 1041 Jun 26 11:28 server.csr 1675 Jun 26 11:29 server.key 4. Copy your new certificate files to the Apache config directory. The location of this directory will differ depending on how Apache was compiled. cp /root/ssl/server.key /etc/httpd/conf/ssl.key/ cp /root/ssl/server.crt /etc/httpd/conf/ssl.crt. Step 3: Configure Apache as an SSL proxy for JIRA Now you need to configure JIRA with Virtual hosting. Step 4: Configure Tomcat (JIRA’s default JAVA application server) The proxyName and proxyPort attributes can be used when Tomcat is run behind a proxy server. If you did not configure these attributes, the values returned would reflect the server name and port on which the connection from the proxy server was received, rather than the server name and port to which the client directed the original request. 1. Add the following lines to the <Connector ... />. Be sure to change “YourDomain” to your proxy’s domain name! vim {JIRA_INSTALL}/conf/server.xml … <Connector port=8080” Scheme=”https” proxyName=”YourDomain” proxyPort=”443” address=”localhost” … /> … 1. Create a file called jira.conf within the conf.d Apache directory: vim /etc/httpd/conf.d/jira.conf 2. Edit conf/server.xml. Locate and change the start of the line from <Context path=”/” to <Context path=”/jira” 3. Restart the Tomcat and Apache servers and check the logs files for errors. Your server should now be accessible at https://YourDomain/jira Add the following: <VirtualHost *:443> ServerName public.server.name ProxyRequests Off ProxyPreserveHost On SSLEngine on SSLCertificateFile /path/to/your/certificate/file SSLCertificateKeyFile /path/to/your/certificate/key/file <Proxy *> Order deny,allow Allow from all </Proxy> ProxyPass /jira https://localhost:8080/jira ProxyPassReverse /jira https://localhost:8080/jira Conclusion If you know what steps to follow, configuring JIRA to work behind an Apache proxy is a relatively straight-forward process. However, if you have any questions, Coyote Creek is here to help you. In fact, we won an Atlassian Experts Award in 2011. Our status with Atlassian means that you can rely on us for top quality Atlassian services and that you can also buy Atlassian products from us. Whatever you need, whether it’s setting up a proxy server or designing and deploying a new Atlassian application, please give Coyote Creek a call. </VirtualHost> 2. Save and exit the configuration file. Note that we’re using localhost as the proxy target. We can do this since we enabled ProxyPreserveHost. The official Apache documentation states that: “It is mostly useful in special configurations like proxied mass namebased virtual hosting, where the original Host header needs to be evaluated by the backend server.” 2 tel 1.888.269.6838 coyotecrk.com About Coyote Creek Founded in 1998 by a team of former corporate IT professionals, Coyote Creek understands the issues and complexities that are part of large-scale IT environments. Pragmatic and vendor neutral, Coyote Creek brings deep expertise to help customers manage technology and project risk, inspiring confidence and creating peace of mind.