Integrating Jira applications with a Web server

On this page

Related content

Still need help?

The content on this page relates to platforms that 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.

“Ghostcat” vulnerability in Apache Tomcat

Following this guide might make your Jira instance prone to a recent high-risk vulnerability found in Apache Tomcat.

Until then, if you need to use the AJP Connector, there are steps you can take to mitigate this issue. For more info, see this article.

This page describes how to configure Microsoft's IIS web server and Jira such that IIS forwards requests on to Jira, and responses back to the user. This is useful if you already have IIS running serving web pages (e.g. http://mycompany.com), and wish to integrate Jira as just another URL (e.g. http://mycompany.com/jira).

Jira is written in Java, and needs a Java Application Server (servlet container) to run. As IIS does not provide services of a Java Application Server, it is not possible to deploy Jira directly into IIS. It is possible, however, to configure IIS to proxy requests for Jira to an application server where Jira is deployed. Therefore, if your main website is running in IIS, it is possible to integrate Jira into this website.

If you need to integrate Jira with IIS, Jira needs to be deployed into a Java application server (such as Apache Tomcat), which provides IIS integration capability.

If you are running Jira against an application server other than Apache Tomcat, please consult that application server's documentation to determine whether it is possible (and how) to integrate the application server with IIS.

1. Configure Jira

Follow the Jira installation guide to install and configure Jira. Note that Jira can be installed on the same machine as IIS, but this is not necessary.

Change the context path of the Jira web application:To allow IIS to proxy requests to Jira, Jira web application must be deployed with a context path (e.g. the /jira in http://localhost:8080/jira (http://localhost:8080*/jira*)) in Tomcat. The context path must be set to the path in the URL that IIS will use to proxy requests. For example, if your website is running with address www.example.com in IIS, and you would like to make Jira available under www.example.com/jira, you will need to set Jira's context path to "/jira" in Tomcat.To do this, edit the conf/server.xml file. Change the path attribute of the Context element to "/jira".

Turn Jira's GZip compression OFF (since there will be no benefit from GZip compression once proxying is implemented).

Test that Jira works correctly by pointing your web browser directly at Tomcat (e.g. http://localhost:8080/jira) and going through Jira's Setup Wizard. If you have completed the Setup Wizard previously, try creating an issue or editing one. Please ensure that no errors occur.

2. Configure Tomcat to accept proxied requests

HTTP/1.1 Connector

If you are using the HTTP/1.1 Connector, you will need to add the following attributes to the Connector port in Tomcat's server.xml:

Enable AJP/1.3 Connector in Tomcat: To allow Tomcat to accept requests for Jira from IIS, edit the conf/server.xml file and ensure that the AJP/1.3 Connector is enabled (i.e. not commented out). To enable the AJP/1.3 Connector in a Jira remove the comment symbols around the following section in the conf/server.xml file:

The above example configures Tomcat to listen for proxied IIS requests on port 8009. If this port is already in use on the machine where Jira is running, please change to another port.

Restart Tomcat and ensure that no errors regarding used ports appear in the logs or in the Tomcat Console.

Ensure that the AJP Connector is listening on the specified port (8009 by default). One way to do this is to use the "netstat -na" command in the command window and see if port 8009 is listed in the output:

3. Configure IIS to forward requests to Jira

On the machine where IIS is deployed:

Download the ISAPI Redirect DLL from the Apache site. When downloading, choose the version of Windows that IIS is running on (either win32 or win64), and then choose the latest available jk version.

The file to download is named isapi_redirect_X.X.X.dll, where 'X.X.X' is the version number. You will need to remove the version number from the DLL file (i.e. it needs to be named isapi_redirect.dll).

Place the DLL and the associated properties files in an installation directory. For the purpose of this document, we will assume the directory is C:\tomcat_iis_connector. Place the isapi_redirect.dll in this directory. Then download the isapi_redirect.properties file and place this in the same directory as the isapi_redirect.dll file.

Create a directory called 'logs' (C:\tomcat_iis_connector\logs). This is where the logs associated with the isapi_redirect.dll execution will be placed.

In the "C:\tomcat_iis_connector" directory you may need to modify the isapi_redirect.properties file. The isapi_redirect.propertiesfile tells the connector where to find its configuration files and where the DLL can be found in relation to the IIS server. There are 5 properties in this file:

extension_uri — the path to the virtual directory that contains the isapi_redirect.dll

worker_mount_file — the path to your uriworkermap.propertiesl file in your installation.If you are installing the connector in C:\tomcat_iis_connector and you follow the instructions below about setting up the virtual directory for the isapi_redirect.dll, then you should not have to change any properties in the provided file.

In the "C:\tomcat_iis_connector\conf" directory you may need to modify the uriworkermap.properties and the workers.properties.minimalfiles.

The provided files contain the changes mentioned here and should work if you completely follow this document. If you have deviated from this document, then you will need to modify these files as described below.

The workers.properties.minimal file tells IIS where (IP address and port) Tomcat is running. The uriworkermap.properties tells IIS what requests to proxy to Tomcat.To edit these files:

Edit the uriworkermap.propertiesand ensure that it contains the following mapping for Jira. You do not need any other mappings.

/jira/*=worker1

The mapping (e.g. /jira/) *must be the same as the context path that Jira has been deployed with in Tomcat as described in the Configure Jira section of this document.

Edit the workers.properties.minimal file and modify the worker.ajp13w.host property if necessary. This property should be set to the host name or the IP address of the machine where Tomcat (with Jira) is running. If Tomcat is running on the same machine as IIS then you can leave the property set to localhost. If you have specified a host name as the value of this property, please ensure that the IIS machine can correctly resolve it to the appropriate IP address.

If you have modified the port for the AJP Connector you will need to modify the worker.ajp13w.portproperty. Here is an example of the file with Tomcat running on the same machine as IIS and using the default port (8009) for AJP:

worker.list=worker1
#
# Defining a worker named worker1 and of type ajp13.
# Note that the name and the type do not have to match.
#
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009

Open Control Panel, then Administrative Tools and open Internet Information Services.

IIS 7.0 only: If you are using IIS 7.0,you will need to install two required service roles, ISAPI Extensions and ISAPI Filters:

Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to Jira), and click on Properties.

Click the ISAPI Filters tab.

Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the right location. If not, click Add and create one. Enter tomcat as the Filter Name and enter the location of the isapi_redirect.dll file for the executable.

Click Apply and then OK.

IIS 7.0:

Click the Default Web Site (or the Web Site that should be responsible for proxying requests to Jira), and click on ISAPI Filters.

Click the ISAPI Filters icon.

Check if there is a Filter that points to the isapi_redirect.dll file and that it is in the right location. If not, click Add and create one. Enter tomcat as the Filter Name and enter the location of the isapi_redirect.dll file.

Click OK.

Create a virtual directoryfor Jira in IIS.

Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to Jira), choose New and then Virtual Directory.

Go through the creation wizard. Set the alias as the value of the Context Path (without slashes) that was set in the Configure Jira section of this document (see above). In our example this is jira .

Click 'Edit Feature Permissions' in the Action panel on the right-hand side.

Check the 'Execute' permission checkbox.

This Virtual Directory is needed for the connector to work. The alias that you give the directory needs to be the same as the path set in the isapi_redirect.properties file, extension_uri property. In our example this value is: /jakarta/isapi_redirect.dll.

If using IIS 6.0 or 7.0, you will need to add the dll as a Web Service Extension,as described below.

IIS 6.0:

Right-click on Web Service Extensions and choose Add a new Web Service Extension...

Enter tomcat for the Extension Name and then add the isapi_redirect.dll file to the required files.

Select the Set extension status to Allowed checkbox, then click OK.

IIS 7.0:

Navigate to the servers and highlight your server.

Navigate to 'ISAPI and CGI Restrictions'.

Add and allow the isapi_redirect.dll extension.

You will need to restart the IIS Service. To do this, browse to Control Panel, click Administrative Tools, click on Services, find the IIS Admin Service and click restart.

You are done! To test the configuration, point your web browser at IIS and append Jira's context path to the URL. For example, if your website is running under the address of http://www.example.com and you have deployed Jira with the context path of jira, point your browser at http://www.example.com/jira.

Troubleshooting

Whenever I go to Jira in my browser, a login panel pops up. I enter a valid username and password for Jira, but the panel pops up again.Make sure that you have Anonymous Access set on the jira virtual directory in IIS. It will be set to that if you have followed the above instructions.To check this:

In 'Internet Information Services', right click the jira virtual directory and choose 'Properties'.

Click the 'Directory Security' tab.

Click the 'Edit...' button in the 'Anonymous access and authentication control' section.

Make sure that the 'Anonymous access' tick box is selected, and make sure that nothing is selected in the 'Authenticated access' section. Do not select 'Basic authentication'. Do not select 'Integrated Windows authentication'.

Whenever I go to Jira in Internet Explorer, a login panel pops up. I enter a valid username and password for Jira, but the panel pops up again. This doesn't happen, however, in another browser such as Firefox or Safari. I can successfully log in to Jira in those browsers.Make sure that you have Internet Explorer's User Authentication set to Anonymous login.To check this:

When I try to navigate to my Jira instance athttp://localhost/jirain my browser, it prompts me to download a file with nonsensical information, rather than showing me my Jira instance.Make sure that you have granted the 'Execute' permission to your Virtual Directory for Jira in IIS. See step 11 of the '3. Configure IIS to forward requests to Jira' section in this document for detailed instructions.