Configure an outbound proxy for use in Jira server

Still need help?

The Atlassian Community is here for you.

Ask the 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

The content on this page relates to platforms which are not supported for JIRA Applications. Consequently, Atlassian cannot 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.

  • This Outbound Proxy configuration only works for HTTP and HTTPs request only. If you are trying to connect JIRA to a Mail Server (Gmail or Office365) or to an LDAP Server, this configuration will not work.
  • The https.proxyHost property can not be used in combination with the socksProxyHost property. (Not supported by the outgoing httpclient and will lead to unexpected results)

Purpose

This page defines how to configure JIRA applications such that they can communicate externally through an outbound proxy. This is required to access servers outside the network it's hosted in, such as the Atlassian Marketplace. If you wish to host JIRA applications behind a reverse-proxy (or inbound proxy), please refer to Integrating JIRA with Apache or Integrating JIRA with Apache using SSL.

Adding JVM properties

All properties discussed in this article are Java Virtual Machine (JVM) parameters.

JVM properties are set in setenv scripts

To add the parameters to Jira's JVM:

  1. Modify the relevant startup script (setenv.sh/setenv.bat)
  2. Restart Jira 

(info) For complete instructions on the process of adding properties to the JVM on startup, please see our Setting Properties and Options on Startup documentation.  This documentation also explains how to verify the settings have taken effect.

Proxy configuration

Proxy Support is configured in JIRA applications by passing certain system properties to the Java Virtual Machine (JVM) on startup. These properties follow the conventions defined by Oracle:

  • http.proxyHost
  • http.proxyPort (default: 80)
  • http.nonProxyHosts (default: <none>)
  • https.proxyHost
  • https.proxyPort

The http.proxyHost property must be defined to configure an HTTP proxy, and https.proxyHost for an HTTPS proxy.

The http.proxyHost and http.proxyPort properties indicate the proxy server and the port that the HTTP protocol handler will use. For example:

-Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.org -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts=localhost

The property http.nonProxyHosts indicates the hosts which should be connected to directly and not through the proxy server. The value can be a list of hosts, each separated by a ( | ), and in addition a wildcard character ( * ) can be used for matching. For example:

-Dhttp.nonProxyHosts=*.foo.com|localhost|confluence|crowd

The pipe character ( | ) may need to be escaped in Linux

The pipe character ( | ) may not work in the latest versions of Windows with the latest Windows update

tip/resting Created with Sketch.

Please refer to JAVA Option '-Dhttp.nonProxyHosts' Does Not Work KB article for more details.


If the http.nonProxyHosts property is not configured, all web requests will be routed through the proxy. For example, if connecting Confluence and JIRA applications together with Application Links, we would recommend bypassing the proxy and communicating on the internal network with this property. Routing through the proxy can have ramifications when taking into account IP validation on those links - the source IP of the server can be different depending on how the traffic is routed.

At the minimum, the http.nonProxyHosts must include localhost and JIRA baseurl, otherwise certain functionality may not properly work (JIRA tries to connect to itself and HTTP request can timeout or be blocked by proxy). For example:

-Dhttp.nonProxyHosts=localhost|jira.atlassian.com

If connecting JIRA applications to any other applications, the application URL should be added to the nonProxyHosts argument. Otherwise what can happen is when JIRA applications attempt to talk to another Atlassian application the HTTP request can timeout, or not resolve. This will prevent the applications from linking. For example when connecting JIRA applications to Confluence (located on confluence.atlassian.com):

-Dhttp.nonProxyHosts=localhost|*.atlassian.com

Configuring Authentication

Proxy authentication is configured by passing the below properties to Java, as in our Setting Properties and Options on Startup documentation.

  • http.proxyUser – username
  • http.proxyPassword – secret
  • https.proxyUser
  • https.proxyPassword

For example:

-Dhttp.proxyUser=atlaspirate -Dhttp.proxyPassword=yarrrrr -Dhttps.proxyUser=atlaspirate -Dhttps.proxyPassword=yarrrrr

Microsoft ISA NTLM Authentication

As in our JIRA is Unable to Use NTLM Authentication KB article, JIRA applications do not currently support all configurations of NTLM authentication. However, to configure this with the JVM, the below property is used:

-Dhttp.auth.ntlm.domain=DOMAIN

Configuring Authentication Order

There are three authentication mechanisms provided - ntlmdigestbasic in that order by default. It is possible to change the order and also not exclude one or more methods altogether. This can be done with the following property.

-Dhttp.proxyAuth=basic,ntlm

In this example, the authentication order will be basic and then ntlm onlydigest will not be used.

DescriptionThis page defines how to configure JIRA applications such that they can communicate externally through an outbound proxy. This is required to access servers outside the network it's hosted in, such as the Atlassian Marketplace. 
ProductJira
PlatformServer
Last modified on Sep 7, 2023

Was this helpful?

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