Trusted proxies

When the redirection.io agent is used as a reverse proxy, it is usually deployed in front of one or more backend servers. It may also be deployed behind a load balancer or a CDN. In these cases, the agent needs to be configured to trust the proxies that are forwarding the requests to it, in order to correctly identify the client's IP address and other information that may be lost when the request is forwarded to the agent.

The trusted_proxies configuration node allows you to fine-tune the trusted proxies behavior:

• list the IP addresses of the proxies that you want to trust
• specify whether or not to individually trust the Forwarded, X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers sent by the proxies, which are commonly used to forward the client's IP address and other information

Default behavior

When the trusted_proxies node is not defined, the agent applies the following defaults:

• all the private IP addresses are trusted: loopback addresses, link-local addresses, and the private ranges defined by RFC 1918 (10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16)
• the Forwarded and X-Forwarded-For headers sent by these proxies are trusted
• the X-Forwarded-Proto and X-Forwarded-Host headers are not trusted

The two last headers must be enabled explicitly, for a good reason: trusting them means letting the caller decide which scheme and which domain name are used to match rules and to record logs. Enable them only when the proxy running in front of the agent always sets them, and always overwrites the value that a client could have sent.

Note that the ips directive is optional: if you do not define it, the private IP addresses listed above are trusted. This is convenient when the agent runs in a container or in an orchestrator, where the address of the proxy in front of it is not known in advance.

Running the agent behind a TLS termination proxy

It is very common to run the agent behind a load balancer, a CDN, or another reverse proxy (HAProxy, Varnish, nginx, Envoy, Traefik, an AWS load balancer, Cloudflare, etc.) which terminates the TLS connection and forwards the requests to the agent as plain HTTP requests.

In such a setup, and as long as the agent does not trust the X-Forwarded-Proto header, these requests are seen as http requests, even though the client actually performed an https request. This has two visible consequences:

• requests are logged with the http scheme in the redirection.io manager
• rules using triggers with absolute URLs (https://example.com/some-page) never match

To get the original scheme back, trust the X-Forwarded-Proto header sent by the TLS termination proxy:

The agent then determines the scheme of the request by reading the Forwarded header first, then the X-Forwarded-Proto header, and finally falls back to the scheme of the connection it received. Requests forwarded in plain HTTP by your TLS termination proxy are then matched and logged as https requests.

The same applies to the domain name, with the X-Forwarded-Host header, when the proxy running in front of the agent rewrites the Host header of the requests.

If the proxy in front of the agent sends none of these headers, you can still force the scheme and the host used for matching, with the override_request_scheme and override_request_host directives. Trusted proxies should nevertheless be preferred whenever possible, as they preserve the real value of each request.

A more detailed example

The trusted_proxies node also allows to restrict the list of trusted proxies, and to disable the headers that you do not want to trust. For example, see the following configuration:

instance:
    name: 'My Instance'
reverse_proxy:
    listen:
        - 'tcp://0.0.0.0:80'
    trusted_proxies:
        ips:
            - 192.168.0.0/16
            - 172.16.0.16
        forwarded: true
        x_forwarded_for: true
        x_forwarded_host: false
        x_forwarded_proto: true
    forward:
        address: 'backend:8080'
    agent:
        project_key: my-project-key

With this configuration, the agent will trust the Forwarded and X-Forwarded-For headers that could be passed by the proxies at the IP addresses 172.16.0.16 or in the CIDR range 192.168.0.0/16. It will also trust the X-Forwarded-Proto header, but not the X-Forwarded-Host header. Requests coming from any other IP address are considered as direct client requests, and all their forwarding headers are ignored.