Integrating JIRA applications with IIS

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.

To integrate JIRA with IIS you will need to:

1. Configure JIRA and test that it works on its own
2. Configure Tomcat to accept proxied requests from IIS
3. Configure IIS to forward JIRA requests to Tomcat

1. Configure JIRA

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

2. 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".

3. Restart JIRA after changing the context path.
4. Set the 'Base URL' to include the context path (see Configuring JIRA options).
5. Turn JIRA's GZip compression OFF (since there will be no benefit from GZip compression once proxying is implemented).
6. 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

proxyName="mycompany.com" proxyPort="80"

1. 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:

   <Connector port="8009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />          

   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.

2. Restart Tomcat and ensure that no errors regarding used ports appear in the logs or in the Tomcat Console.
3. 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:

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

2. 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.
3. Create a directory called 'conf' in your installation directory (C:\tomcat_iis_connector\conf). Download the files uriworkermap.properties and workers.properties.minimal and place them in the C:\tomcat_iis_connector\conf directory.
4. 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.
5. 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:
   1. extension_uri — the path to the virtual directory that contains the isapi_redirect.dll
   2. log_file — the path to write the log file to
   3. log_level — the level at which the logs should be generated
   4. worker_file — the path to your workers.properties.minimal file in your installation
   5. 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.

6. 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:

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

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

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

7. Open Control Panel, then Administrative Tools and open Internet Information Services.
8. 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:
   1. Navigate to Start Menu > All Programs > Administration Tools > Service Manager.
   2. Select 'Web Server (IIS)' in Server Manager > Roles.
   3. Click 'Add Role Services' and follow the Wizard.
9. Add an ISAPI Filterto IIS, as described below:
   • IIS 6.0 or earlier:
     1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and click on Properties.
     2. Click the ISAPI Filters tab.
     3. 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.
     4. Click Apply and then OK.
   • IIS 7.0:
     1. Click the Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and click on ISAPI Filters.
     2. Click the ISAPI Filters icon.
     3. 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.
     4. Click OK.
10. Create a virtual directoryfor JIRA in IIS.
    1. 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.
    2. 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 .
    3. This can point to any directory.

    4. Complete the wizard.

       The reason for creating a virtual directory is so that requests without the trailing slash still work. For example, if you are deploying JIRA under http://www.example.com/jira/ without the virtual directory, then requests to http://www.example.com/jira will fail.

11. Create a virtual directory for access to the isapi_redirect.dllin IIS, as described below:
    • IIS 6.0 or earlier:
      1. 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.
      2. Go through the creation wizard. Set the alias to be jakarta .
      3. This must point to the directory in which the isapi_redirect.dll is installed. In our example this is C:\tomcat_iis_connector.
      4. Complete the wizard, making sure that you grant the 'Execute' permission for the Virtual Directory by checking the 'Execute' checkbox.
    • IIS 7.0:
      1. Right-click on Default Web Site (or the Web Site that should be responsible for proxying requests to JIRA), and choose Add Virtual Directory.
      2. Set the alias to be jakarta .
      3. Physical Path must point to the directory in which the isapi_redirect.dll is installed. In our example this is C:\tomcat_iis_connector.
      4. Click the 'jakarta' Virtual Directory and double-click 'Handler Mappings'.
      5. Click 'Edit Feature Permissions' in the Action panel on the right-hand side.

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

12. 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:
      1. Right-click on Web Service Extensions and choose Add a new Web Service Extension...
      2. Enter tomcat for the Extension Name and then add the isapi_redirect.dll file to the required files.
      3. Select the Set extension status to Allowed checkbox, then click OK.
    • IIS 7.0:
      1. Navigate to the servers and highlight your server.
      2. Navigate to 'ISAPI and CGI Restrictions'.
      3. Add and allow the isapi_redirect.dll extension.
13. 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.
14. 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:
  1. In 'Internet Information Services', right click the jira virtual directory and choose 'Properties'.
  2. Click the 'Directory Security' tab.
  3. Click the 'Edit...' button in the 'Anonymous access and authentication control' section.
  4. 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:
  1. In Internet Explorer, click the 'Tools' menu and select 'Internet Options'.
  2. Click the 'Security' tab.
  3. Select the security zone that the JIRA server is in.
  4. Click the 'Custom level...' button.
  5. Scroll right down to the bottom to the 'User Authentication' section.
  6. Select 'Anonymous logon' (if it is not already selected).
  7. Click the 'OK' button on this screen, and again on the next screen.
  8. Restart Internet Explorer.

• When I try to navigate to my JIRA instance at http://localhost/jira in 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.

Known issues

• 64 bit IIS: If you are running a 64 bit OS, please use a 64 bit version of the Tomcat IIS connector.
• Customer submitted solution: If you must use a 32 bit IIS connector, you can do so by clicking Application Pools > Advanced Settings > Allow 32bit applications.
• Customer submitted solution: You need to set the ISAPI extension on the website.