.. _proxy_headers:

*************
Proxy Headers
*************

Before a request is forwarded to an origin, it is equipped with a set of "forwarded headers", depending on configuration. If the origin can handle multiple brands/tenants, the brand identifier can also be set as a header.

The original ``Host`` header is always reserved, unless it is configured to be set to a certain brand identifier.


.. _headers_config:

Configuration
-------------

The following settings are applicable to ``application.properties``.

:proxy.headers.preserve: Depending on whether the proxy instance is the initial proxy or already placed behind another HTTP proxy, it can be configured to preserve existing forwarded headers. Otherwise existing headers will be removed for security reasons.

                                                 If headers are preserved, inbound ``X-Forwarded-Host`` headers are considered for :ref:`virtual host matching <routing_virtual_hosts>`.

                                                 Default: ``false``

                                                 Reloadable: ``false``

                                                 EnvVar: ``PROXY_HEADERS_PRESERVE``

:proxy.headers.brand.name: The header name which will carry the brand identifier, if a brand was determined by the routing engine. For brand identification, see :ref:`routing_virtual_hosts`.

                                       Default: ``Host``

                                       Reloadable: ``true``

                                       EnvVar: ``PROXY_HEADERS_BRAND_NAME``


Headers
-------

:X-Forwarded-For: Stores the original client IP. If the header was preserved on an incoming request, the client IP is appended to the existing value in form of ``<old-value>, <client-ip>``.

                  IPv6 addresses are formatted with surrounding brackets, e.g. ``[2001:db8:cafe::17]``.

:X-Forwarded-Port: Stores the port the request was received on.

:X-Forwarded-Proto: Stores the original URI scheme/protocol, i.e. ``https`` or ``http``.

:X-Forwarded-Host: Stores the original ``Host`` header.

:<brand-header>: Stores the brand identifier, if it could be determined based on routing configuration. The header name is based on configuration value of ``proxy.headers.brand.name``. Per default, the ``Host`` header is overridden.