Proxying Atlassian server applications with Microsoft Internet Information Services (IIS)

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

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

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

This page explains how to establish a network topology in which Internet Information Services (IIS) acts as a reverse proxy for Atlassian server applications. The page has been written as a recipe for success – we recommend you follow it step by step. 

 You might consider using a reverse proxy when you want users to access the Atlassian applications: 

  • at their own domains, such as   http://our<atlassianapp>.com/
  • at subdomains of another domain, such as  http://my<atlassianapp>.example.com/
  • at context paths on either a domain or subdomain, such as   http://example.com/my<atlassianapp>
  • on different HTTP ports, such as 9800, 9850, etc.

For more complex scenarios, you can refer to the Microsoft IIS Documentation, consult with an Internet Information Services (IIS) specialist in your organisation, ask the Atlassian Community, or contact an Atlassian Partner.

The instructions on this page apply to the following Atlassian server applications:

  • JIRA server applications (JIRA Software Server, JIRA Core, JIRA Service Desk)
  • Confluence Server
  • Bamboo Server
  • Bitbucket Server
  • Fisheye
  • Crucible
  • Crowd

In the examples that follow on this page, <atlassianapp> refers to the name of any of the Atlassian server applications above.


Atlassian server applications bundle a web server, which allows them to run without needing a proxy server. For most Atlassian applications, the bundled web server is Apache Tomcat (Fisheye and Crucible use Jetty). Consequently, you need to configure both Tomcat (or Jetty if using Fisheye or Crucible) and IIS when proxying an Atlassian application.


Prerequisites

You'll need the following:

Internet Information Services (IIS) version 7.0, 8.0 or 10.0 installed

You may find it helpful to refer to the Microsoft IIS Documentation to install IIS in your Microsoft Windows Server. (http://www.iis.net/learn/get-started/whats-new-in-iis-8/installing-iis-8-on-windows-server-2012)

DNS entries in place and configured for your domains

You should check, perhaps with your system or network administrator, whether the current DNS configuration for your organization will need changes to support the proxy topology you wish to set up.

The Atlassian applications installed, and accessible through a web browser

Install the Atlassian applications in the usual way.

Part A. Configure the Atlassian applications

This section describes how to configure the Tomcat (or Jetty) web server bundled with each Atlassian application to run behind a reverse proxy.

1. Stop the Atlassian applications

Stopping the application also stops Tomcat.

In Windows, Atlassian applications are typically stopped/started using scripts in the "bin" directory where you installed the product. Alternatively, you may have setup the application to run as a Windows Service.

See the documentation for your product for instructions:

2. Set the context path

This step is only required if you want an application to be accessed on a context path, such as  http://ourcompany.com/<contextpath> . If this is not required, you can skip this step.

Fisheye and Crucible

If you're proxying Fisheye or Crucible, configure the web context path for Jetty from the admin area. See Configuring the Fisheye web server.

Once you've done that, continue with Part B below.

Bitbucket Server 5.0+

In Bitbucket Server 5.0+, the context path can be changed by modifying server.context-path in $BITBUCKET_HOME/shared/bitbucket.properties

bitbucket.properties
server.context-path=/bitbucket
JIRA applications, Confluence, Bitbucket Server 4.x and below, Bamboo

If you're proxying any of these Atlassian server applications, configure the context path in the Tomcat server.xml file as follows.

The location of your server.xml file depends on your application, operating system, and installation location. 

Common default installation locations for Atlassian applications are:

  • Linux: /opt/atlassian/<application-name>
  • Windows: C:\Program Files\Atlassian\<application-name>
  • Windows: C:\Atlassian\<application-name>

Locations in Atlassian application's folder structure:

Applicationserver.xml location
Bamboo<install-path>/conf/
Confluence<install-path>/conf/
Crowd<install-path>/apache-tomcat/conf/
CrucibleAs for Fisheye.
FisheyeThe Fisheye configuration file is config.xml, see Configuring the Fisheye web server and How to enable Fisheye/Crucible to listen to web requests on additional ports.
JIRA applications<install-path>/conf/
Bitbucket Server 5.0

N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties

Bitbucket Server 4.0 – 4.14<Bitbucket home directory> /shared/server.xml
Stash 3.8 – 3.11

<Stash home directory>/shared/

If you are on any of these later releases but your server.xml does not exist in the directory above, it means that you are running from the <install-path>/conf/server.xml.

We recommend that you copy <install-path>/conf/server.xml into <Stash home directory>/shared/ that way you won't need to worry about this when you upgrade your instance.


Stash 3.7 and earlier<install-path>/conf/

<install-path> refers to where the application was installed on your system.

 


<Context path="" docBase="${catalina.home}/atlassian-<atlassianapp>" reloadable="false" useHttpOnly="true">

In the Tomcat server.xml configuration file for all applications except Crowd, locate the Context directive that looks like this:

Change the directive to add the new context path:

<Context path="/<contextpath>" docBase="${catalina.home}/atlassian-<atlassianapp>" reloadable="false" useHttpOnly="true">

Use your own value for <contextpath>. Typically, each application would use a different context path.

It is important that the path value has a leading forward slash (/) like path="/<contextpath>" rather than path="<contextpath>".

Use these instructions to update the Crowd context path.

3. Configure the Connector directive

3.1. Configure Fisheye/Crucible web server (Jetty)

If you're using Fisheye or Crucible, configure the proxy host, proxy scheme and the proxy port from the Admin area. See Configuring the Fisheye web server.

If you are configuring Bitbucket Server 5.0

As of Bitbucket Server 5.0, you can't configure any Tomcat connectors directly, therefore the configurations in this section only apply for Bitbucket server 4.14 or earlier.

server.xml configurations have been replaced by <Bitbucket home directory> /shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties to check the corresponding properties and and to translate the configuration below. After finishing the mapping to bitbucket.properties go to Part B. Configure SSL.

It is possible to change the configuration also directly in the config.xml by having a configuration similar to:

<web-server site-url="http://<subdomain>.<domain>.com" context="">
   <http bind=":8060" proxy-port="80" proxy-scheme="http" proxy-host="<subdomain>.<domain>.com"/> 
</web-server>


3.2. Configure other Atlassian applications web server (Tomcat)

If you're using any of the other Atlassian server applications, configure the Connector directive as follows.

For each application, find the normal (non-SSL) Connector directive in the Tomcat server.xml file, and add the scheme,  proxyName, and proxyPort attributes inside the Connector directive, as below. Use the default values for the other attributes, including for  port , unless you have a particular reason to change them, and use your own domain name for the proxyName value:

<Connector port=<default>
	maxThreads=<default>
    minSpareThreads=<default>
    connectionTimeout=<default>
    enableLookups=<default>
    maxHttpHeaderSize=<default>
    protocol=<default>
    useBodyEncodingForURI=<default>
    redirectPort=<default>
    acceptCount=<default>
    disableUploadTimeout=<default>
	proxyName="<subdomain>.<domain>.com"
	proxyPort="80"
	scheme="http"/>

Note that the proxyName parameter should be set to the FQDN that IIS will be configured to serve. This is the address a user would type into their browser to access the application. For example:

  • use <atlassianapp>.example.com to access the application at a sub-domain like http://<atlassianapp>.example.com/
  • use example.com  to access the application at a context path like  http://example.com/<atlassianapp> . In this case, the context path should not be included in the proxyName parameter, and you would have already set the Context directive in step 2 above.
  • use proxyPort="443" and scheme="https" in case the SSL is being terminate at IIS.

For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.


If you previously had HTTPS redirection implemented directly in Tomcat (e.g. Running Jira over HTTPS) – you may need to update the <jira-install>/WEB-INF/web.xml file to remove Tomcat redirect rules that specify the security-constraint section since you will be using IIS redirection instead.


Part B. Configure Internet Information Services (IIS)

1. Be sure you have ARR, URL rewrite and Request Filtering installed on your IIS server

In case you do not have Application Request Routing and URL Rewrite on your IIS server install them using Application Request Routing Installer.

In case Request Filtering is not installed in your IIS instance you can install it following https://www.iis.net/configreference/system.webserver/security/requestfiltering.

2. Enable Proxying on ARR

  1. From the IIS7 Console, click on Server_Name and  open Application Request Routing Cache:
  2. From the Actions panel on the right hand side, select  "Server Proxy Settings"
     
  3. Check "Enable Proxy" and set HTTP Version to "HTTP/1.1":
  4. Deselect "Reverse rewrite host in response headers" then leave all the other options on the default value and click on Apply to apply the changes.

3. Add an Application Pool and new IIS website 

Create an Application Pool for Atlassian applications and change the the .NET CLR Version to "No Managed Code". Please see How to create a new application pool for more details. If your site is configured with Default Pool and it's being shared, and ASP.NET is registered with IIS, it may cause some unexpected behavior in Atlassian applications, especially for integration features like Smart commits etc.

Next step, create a IIS website to configure the redirect. More info on how to create a Web Site on IIS can be found at How to set up your first IIS Web site. Configure this website to use the Application Pool created in the earlier step.

 In this article the site added is jira.example.com. You can change it with the correct one for your instance/domain. When a web site is created in IIS, it needs a DocumentRoot to be specified. Since this is for a redirect purpose, the DocuementRoot path itself is not important - it can be inside IIS directory or any other path since the requests are redirected to Jira.


4. Add a new URL rewrite rule

  1. From the IIS Console, click on  jira.example.com  and open URL Rewrite:
  2. From the Actions panel on the right hand side, select "Add Rules" and choose "Blank Rule";
  3. Add a name for the rule;
  4. Set Match URL to:
    1. Requested URLMatches the Pattern
    2. UsingRegular Expressions
    3. Pattern(.*)
    4. Ignore CaseChecked
  5. Set Action to:
    1. Action TypeRewrite
    2. Rewrite URL http://<JIRA_url:Port>/{R:1}
    3. Append query stringChecked
  6. Mark Stop processing of subsequent rules;
  7. Click on Apply to apply the changes.


Rule Order - Redirect before rewrite

If redirection to HTTPS in IIS will be used (recommended), you will need to implement a redirect rule in IIS and position it above/before the URL rewriting rule specified above (this will redirect the query to HTTPS before rewriting it). For an in-depth resource on this, please check out Redirect HTTP to HTTPS with Windows IIS 10.


5. Tune Request Filtering

  1. Double-click on the site name to move in the site configuration section.

  2. Click in Request Filtering

  3. Then click in Edit Feature Settings:
  4. Check Allow double escaping and hit OK:

6. Disable Output Caching

  1. On the Site Home screen in IIS Manager double click on "Output Caching"
  2. On the right side under Actions, click on Edit Feature Settings
  3. Uncheck Enable Cache and Enable kernel cache
  4. Click OK

Enabling caching will have intermittent user session changed. User session changed or hijacked in Jira server integrated with IIS

7. Enable long URLs

Add a registry key as shown below to increase the path length that IIS can handle. This is necessary for some gadgets and buttons to work correctly.

Path: "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters"
Type: DWORD 32-bit
Name: "UrlSegmentMaxLength"
Value: "1000" Hexadezimal

You will need to restart Windows for the changes to take effect. With that, we would recommend scheduling a maintenance window accordingly.

Confluence 6.0 specific notes:

If you're using Confluence 6.0 or later with Synchrony (which is required for collaborative editing), you'll need to ensure the following prerequisites are met:

  1. You must have IIS version 8.0 or higher installed
  2. You must have Web Sockets Support for IIS installed
  3. You must have Application Request Routing 3.0 installed

Please note that at this time we have seen some issues with IIS and Synchrony when pasting text. Pasting text is not possible if it is more than a small amount of text, as indicated in this issue:

CONFSERVER-46504 - Getting issue details... STATUS

You'll also need to use the following rewrite rules in your web.config file:

Sample web.config for Synchrony
<system.webServer>
    <rewrite>
        <rules useOriginalURLEncoding="false">
        <clear />
        <rule name="Synchrony HTTP" stopProcessing="true">
            <match url="^synchrony/(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8091/synchrony/{R:1}" />
        </rule>
        <rule name="Synchrony Web Sockets Reverse Proxy" stopProcessing="true">
            <match url="ws://(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="ws://localhost:8091/{R:1}" />
        </rule>
        <rule name="Unencoded URL for Companion" stopProcessing="true">
            <match url="^download/(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8090{UNENCODED_URL}" appendQueryString="false" />
        </rule>
        <rule name="Confluence Reverse Proxy" stopProcessing="true">
            <match url="(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8090/{R:1}" />
        </rule>
        </rules>
    </rewrite>
    <security>
        <requestFiltering allowDoubleEscaping="true" />
    </security>
    </system.webServer>
    <system.web>
        <!-- This keeps IIS from complaining about special characters in the url. Also has some controls for max upload size. Set to the equivalent of the above, but in kilobytes instead of bytes. (ex. 61440 = 60MB) -->
        <httpRuntime executionTimeout="20" maxRequestLength="xxxxx" requestPathInvalidCharacters="" requestValidationMode="2.0" />
        <pages validateRequest="false" />
    </system.web>

In the example above, Confluence is accessed without a context path and does not use Confluence's internal proxy. See Administering Collaborative Editing for other proxy configuration options.

As IIS 8.0 and above does not support the Sec-WebSockets-Extension permessage-deflate header, you will also need to add the following to your startup parameters:

  • If you start Confluence via startup script on Windows or Linux, add the following parameter to your <install-path>/bin/setenv.bat or setenv.sh 
# For Linux/Unix setenv.sh
CATALINA_OPTS=-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true %CATALINA_OPTS%


# For Windows setenv.bat
set CATALINA_OPTS=-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true %CATALINA_OPTS%
  • If your instance is installed as a Windows service, add the following system property via command line or registry. See Configuring System Properties guide for instructions:
-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true

Part C. Final configuration

Restart each application

Now, restart each application and ensure you can access them using new URLs. See the stopping and starting instructions above.

Set the application Base URL

For each Atlassian application, set the Base URL to the address you configured in the proxy, which is the URL that Internet Information Services (IIS) will be serving (such as  http://www.example.com/<atlassianapp>).

For details see the instructions for your Atlassian product:

Part D. Configure Multiple Sites on the same IIS instance

OPTIONAL: In some cases more than one site will be hosted in the same IIS installation. In case you want to have a subdomain structure (i.e. jira.example.com, confluence.example.com), you may create different sites as follow:


Multiple sites on IIS single instance
  1. Create an A Record in the DNS for your subdomain and point to the same IP
      (info) IIS Reverse proxy server IP. The IP that the users will use to access the IIS. 
  2. Create new sites (step 3 of the instructions above) for each one of your subdomains:
    1. Sites > Add Website
    2. Site Name: subdomain.example.com
    3. Physical Path: select the subdomain directory
    4. Binding: same ip as example.com
    5. Host name: subdomain.example.com

NOTE: For more information about using Host Headers and SSL, you may take a look at this blog-post.

DescriptionThis page explains how to establish a network topology in which Internet Information Services (IIS) acts as a reverse proxy for Atlassian server applications. The page has been written as a recipe for success – we recommend you follow it step by step. 
ProductJira, Confluence, Bamboo, Bitbucket, Fisheye, Crucible, Crowd
PlatformServer
Last modified on Oct 30, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.