Configuring Web Proxy Support for Confluence

Some of Confluence's macros, such as {rss} and {jiraissues} need to make web requests to remote servers in order to retrieve data. If Confluence is deployed within a data centre or DMZ, it may not be able to access the Internet directly to make these requests. If you find that the {rss} macro does not work, ask your network administrator if Confluence needs to access the Internet through a web proxy.

Configuring an outbound HTTP proxy in Confluence

Proxy support is configured by passing certain system properties to the Java Virtual Machine on startup. 

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

At a minimum, you need to define http.proxyHost to configure an HTTP proxy, and https.proxyHost to configure an HTTPS proxy. System property configuration is described in the Configuring System Properties.

Properties http.proxyHost and http.proxyPort indicate the proxy server and port that the http protocol handler will use, and https.proxyHost and https.proxyPort indicate the same for the https protocol handler.

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

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 pipe character | . In addition, a wildcard character (asterisk) * can be used for matching. For example:

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

If you're using Confluence 6.0 or later with Synchrony, you'll need to pass the following to ensure Confluence can connect directly to Synchrony. Replace localhost|127.0.0.1 with your Synchrony IP if you have used the synchrony.host system property to change the IP Synchrony uses. 

-Dhttp.nonProxyHosts=localhost|127.0.0.1
-Dhttps.nonProxyHosts=localhost|127.0.0.1

Note: You may need to escape the pipe character | in some command-line environments.

If the http.nonProxyHosts property is not configured, all web requests will be sent to the proxy.

Please note that any command line parameters set are visible from the process list, and thus anyone who has the approriate access to view the process list will see the proxy information in the clear. To avoid this, you can set these properties in the catalina.properties file, located in confluence-install/conf/. Add this to the end of the file:

http.proxyHost=yourProxyURL
http.proxyPort=yourProxyPort
http.proxyUser=yourUserName
http.proxyPassword=yourPassword
https.proxyHost=yourProxyURL
https.proxyPort=yourProxyPort
https.proxyUser=yourUserName
https.proxyPassword=yourPassword

Configuring HTTP proxy authentication

Proxy authentication is also configured by providing system properties to Java in your application server's configuration file. Specifically, the following two properties:

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

HTTP proxy (Microsoft ISA) NTLM authentication

Confluence supports NTLM authentication for outbound HTTP proxies when Confluence is running on a Windows server.

This means that the {rss} and {jiraissues} macro will be able to contact external websites if requests have to go through a proxy that requires Windows authentication. This support is not related to logging in Confluence users automatically with NTLM, for which there is a user-contributed authenticator available.

To configure NTLM authentication for your HTTP proxy, you need to define a domain system property, http.auth.ntlm.domain, in addition to the properties for host, port and username mentioned above:

-Dhttp.auth.ntlm.domain=MYDOMAIN

Configuring authentication order

Sometimes multiple authentication mechanisms are provided by an HTTP proxy. If you have proxy authentication failure messages, you should first check your username and password, then you can check for this problem by examining the HTTP headers in the proxy failure with a packet sniffer on the Confluence server. (Describing this is outside the scope of this document.)

To set the order for multiple authentication methods, you can set the system property http.proxyAuth to a comma-separated list of authentication methods. The available methods are: ntlm, digest and basic; this is also the default order for these methods.

For example, to attempt Basic authentication before NTLM authentication, and avoid Digest authentication entirely, you can set the http.proxyAuth property to this value:

-Dhttp.proxyAuth=basic,ntlm -Dhttps.proxyAuth=basic,ntlm

Troubleshooting

1. There's a diagnostic jsp file in CONF-9719 for assessing the connection parameters.
2. 'Status Code [407]' errors are described in APR-160.
3. Autoproxies are not supported. See CONFSERVER-16941 - Getting issue details... STATUS .