=======================
WSGITrustedProxyHeaders
=======================

:Description: Specify a list of trusted proxy headers.
:Syntax: ``WSGITrustedProxyHeaders`` *header|(header-1 header-2 ...)*
:Context: server config, virtual host, directory, .htaccess
:Override: ``FileInfo``

When trusted proxies are designated, this is used to specify the headers
which are used to convey information from a proxy to a web server behind the
proxy that are to be trusted.

The IP addresses of the proxies to be trusted should be specified using the
``WSGITrustedProxies`` directive.

As there are multiple conventions for what headers are used to convey
information from the proxy to the web server you need to specify the specific
header from a supported list of headers for a particular purpose that you want
to trust using the ``WSGITrustedProxyHeaders`` directive.

When a request is then received from a trusted proxy, only the header from
the set of headers for that particular purpose is passed through to the WSGI
application and all others will be dropped. If a request was instead from an
IP address which isn't a trusted proxy, then all headers in that set of headers
will be dropped and not passed through.

Depending on the purpose of the header, modifications will be made to other
special variables passed through to the WSGI application. It is these other
variables which is what the WSGI application should consult and the original
header should never be consulted, with it only being provided as an indication
of which header was used to set the special variable.

The different sets of supported headers used by proxies are as follows.

For passing through the IP address of the remote HTTP client the supported
headers are:

* X-Forwarded-For
* X-Client-IP
* X-Real-IP

You should select only one of these headers as the authoritative source for
the IP address of the remote HTTP client as sent by the proxy. Never select
multiple headers because if you do which will be used is indeterminate.

The de-facto standard for this type of header is ``X-Forwarded-For`` and it
is recommended that it be used if your proxy supports it.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Forwarded-For

With this configuration, when a request is received from the trusted proxy only
the ``X-Forwarded-For`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_FORWARDED_FOR`` variable.

For this set of headers, the ``REMOTE_ADDR`` CGI variable as used by WSGI will
be modified and set to the IP address of the remote HTTP client. A WSGI
application in this case should always use ``REMOTE_ADDR`` and never consult
the original header files.

For passing through the protocol of the original request received by the
trusted proxy the supported headers are:

* X-Forwarded-HTTPS
* X-Forwarded-Proto
* X-Forwarded-Scheme
* X-Forwarded-SSL
* X-HTTPS
* X-Scheme

You should select only one of these headers as the authoritative source for what
protocol was used by the remote HTTP client as sent by the proxy. Never select
multiple headers because if you do which will be used is indeterminate.

The de-facto standard for this type of header is ``X-Forwarded-Proto`` and it
is recommended that it be used if your proxy supports it.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Forwarded-Proto

With this configuration, when a request is received from the trusted proxy only
the ``X-Forwarded-Proto`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_FORWARDED_PROTO`` variable.

For this set of headers, the ``wsgi.url_scheme`` variable passed to the WSGI
application will be modified to indicate whether the original request used the
``https`` protocol. Note that although it is a convention when using CGI
scripts with Apache, the mod_wsgi module removes the ``HTTPS`` variable from
the set of variables passed to the WSGI application. You should always use
the ``wsgi.url_scheme`` variable in a WSGI application.

For passing through the host name targeted by the original request received by
the trusted proxy the supported headers are:

* X-Forwarded-Host
* X-Host

You should select only one of these headers as the authoritative source for the
host targeted by the original request as sent by the proxy. Never select
multiple headers because if you do which will be used is indeterminate.

The de-facto standard for this type of header is ``X-Forwarded-Host`` and it
is recommended that it be used if your proxy supports it.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Forwarded-Host

With this configuration, when a request is received from the trusted proxy only
the ``X-Forwarded-Host`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_FORWARDED_HOST`` variable.

For this set of headers, the ``HTTP_HOST`` variable passed to the WSGI
application will be overridden with the value from the header supplied by the
proxy. That is, the value from the proxy for the original request will even
override any explicit ``Host`` header supplied in the request from the proxy,
which in normal cases would be the host of the web server. A WSGI application
should always consult the ``HTTP_HOST`` variable and not the separate header
supplied by the proxy.

For passing through the port targeted by the original request received by the
trusted proxy, the only supported header is:

* X-Forwarded-Port

Although it is the only supported header, you still must select if as a trusted
header to have it processed in the same way as other trusted headers.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Forwarded-Port

With this configuration, when a request is received from the trusted proxy only
the ``X-Forwarded-Port`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_FORWARDED_PORT`` variable.

For this header, the ``SERVER_PORT`` variable passed to the WSGI application
will be overridden with the value from the header supplied by the proxy. A WSGI
application should always consult the ``SERVER_PORT`` variable and not the
separate header supplied by the proxy.

For passing through the host name of any proxy, to use in overriding the host
name of the web server, the only supported header is:

* X-Forwarded-Server

Although it is the only supported header, you still must select if as a trusted
header to have it processed in the same way as other trusted headers.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Forwarded-Server

With this configuration, when a request is received from the trusted proxy only
the ``X-Forwarded-Server`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_FORWARDED_SERVER`` variable.

For this header, the ``SERVER_NAME`` variable passed to the WSGI application
will be overridden with the value from the header supplied by the proxy. A WSGI
application should always consult the ``SERVER_NAME`` variable and not the
separate header supplied by the proxy.

For passing through the apparent URL sub path of a web application, as mapped
by the trusted proxy, the supported headers are:

* X-Script-Name
* X-Forwarded-Script-Name

You should select only one of these headers as the authoritative source for the
host targeted by the original request as sent by the proxy. Never select
multiple headers because if you do which will be used is indeterminate.

The configuration might therefore be::

    WSGITrustedProxies 1.2.3.4
    WSGITrustedProxyHeaders X-Script-Name

With this configuration, when a request is received from the trusted proxy only
the ``X-Script-Name`` header will be passed through to the WSGI application.
This will be done following CGI convention as used by WSGI, namely in the
``HTTP_X_SCRIPT_NAME`` variable.

For this header, the ``SCRIPT_NAME`` variable passed to the WSGI application
will be overridden with the value from the header supplied by the proxy. A WSGI
application should always consult the ``SCRIPT_NAME`` variable and not the
separate header supplied by the proxy.

Examples above show using a single header of a specific purpose at one time.
When you need to trust multiple headers for different purposes, you can list
them separated by spaces using one instance of ``WSGITrustedProxyHeaders``::

    WSGITrustedProxyHeaders X-Forwarded-For X-Forwarded-Host X-Forwarded-Port

or in separate directives::

    WSGITrustedProxyHeaders X-Forwarded-For
    WSGITrustedProxyHeaders X-Forwarded-Host
    WSGITrustedProxyHeaders X-Forwarded-Port

As already highlighted you should only list one header for a specific purpose
when there are multiple conventions for what header to use. Which you use will
depend on the configuration of your proxy. You should only trust headers which
are always set by the proxy, never trust headers which are optionally set by
proxies because if not overridden by a proxy, a remote client could still
supply the header.

Also remember that in general you should not consult the proxied headers
themselves, but instead consult the special variables set from those headers
which are passed to the WSGI application and which are defined as being special
to WSGI. As illustration of how such special variables are used, consider
for example the notes in the WSGI specification around URL reconstruction.

* https://peps.python.org/pep-3333/#url-reconstruction

Finally, if using this feature to trust proxies and designated headers, do not
enable in any WSGI framework or application separate functionality it may have
for also processing the proxy headers. You should only rely on what mod_wsgi
has done to update variables special to WSGI.