iTop and reverse proxies

Starting with version 2.7.4, iTop is compatible with reverse proxies given that the appropriate configuration of the reverse proxy is made.

HTTP headers

During certain phases of execution of iTop (setup, login via SSO…), the application needs information about the original URL requested by the client browser.

When the PHP/Webserver running iTop is accessed via a reverse proxy, the information about the actual HTTP request is not available via the normal HTTP headers, therefore the reverse proxy must provide this additional information. The defacto standard for providing this information is through the use of X-Forwarded-* HTTP headers.

iTop takes into account the following headers:

Header name Meaning
X-Forwarded-Host The host - as seen by the client browser. (e.g. itop.mycompany.com)
X-Forwarded-Port The port used by the client browser. (e.g. 80, 8080, 443…)
X-Forwarded-Proto The protocol used by the client browser. Either http or https
X-Forwarded-Protocol Alternate header for X-forwarded-Proto: the protocol used by the client browser. Either http or https
The reverse proxy must set the HTTP headers X-Forwarded-Host, X-Forwarded-Port and either X-Forwarded-Proto or X-Forwarded-Protocol

Security considerations

The values contained in these headers must only be trusted when they come from a legitimate source (i.e. the reverse proxy).

Since the X-Forwarded-* headers are plain text HTTP headers, it is easy for any web browser client to inject such headers in the request.

To eliminate the need for a complex configuration of the trusted sources (ranges of IP v4 or v6 addresses), iTop uses this strategy:

  1. The root URL of the iTop application is computed (based on the available server information and HTTP headers) during the installation of the application. This value is prompted to the administrator who is responsible for validating it. The X-Forwarded-* HTTP headers are always trusted in this case
  2. when a redirect URL is computed, iTop compares this computed URL with the stored root url. If the computed URL starts with the root URL, the redirection can be safely performed. Otherwise the redirection is performed toward the start page of the application. The X-Forwarded-* HTTP headers are only trusted if you set the behind_reverse_proxy configuration parameter to true.

This mean that your webserver must be accessible only by your proxy (or, in other words, not directly accessible by all public ip adresses).

Timeouts, retries and custom errors

When some lengthy operations are performed by iTop (setup, move to production, database integrity checks), there is a risk that the reverse proxy abandons the request if the application is too slow to answer. Depending on the proxy configuration the request will eb either reported as an error or launched again automatically! This can produce unexpected errors in the application.

To prevent such errors from happening, make sure that:

  1. you configure a long read timeout for the iTop requests (some setup tasks may take one hour to complete on a large to medium size database).
  2. you disable retries (when a request times out, reverse proxies can retry the request, this breaks some pages of iTop)
  3. you disable proxies custom errors (some proxies can intercept error codes and replace the response, this breaks some pages of iTop)
latest/install/reverse_proxy.txt · Last modified: 2023/07/21 10:19 (external edit)
Back to top
Contact us