How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy

Solution: setTrustedProxies()

To fix this, you need to tell Symfony which reverse proxy IP addresses to trust and what headers your reverse proxy uses to send information.

You can do that by setting the SYMFONY_TRUSTED_PROXIES and SYMFONY_TRUSTED_HEADERS environment variables on your machine. Alternatively, you can configure them using the following configuration options:

1
2
3
4
5
6
7
8
9
10
11

# config/packages/framework.yaml
framework:
    # ...
    # the IP address (or range) of your proxy
    trusted_proxies: '192.0.0.1,10.0.0.0/8'
    # shortcut for private IP address ranges of your proxy
    trusted_proxies: 'private_ranges'
    # trust *all* "X-Forwarded-*" headers
    trusted_headers: ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix']
    # or, if your proxy instead uses the "Forwarded" header
    trusted_headers: ['forwarded']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <!-- the IP address (or range) of your proxy -->
        <framework:trusted-proxies>192.0.0.1,10.0.0.0/8</framework:trusted-proxies>
        <!-- shortcut for private IP address ranges of your proxy -->
        <framework:trusted-proxies>private_ranges</framework:trusted-proxies>

        <!-- trust *all* "X-Forwarded-*" headers -->
        <framework:trusted-header>x-forwarded-for</framework:trusted-header>
        <framework:trusted-header>x-forwarded-host</framework:trusted-header>
        <framework:trusted-header>x-forwarded-proto</framework:trusted-header>
        <framework:trusted-header>x-forwarded-port</framework:trusted-header>
        <framework:trusted-header>x-forwarded-prefix</framework:trusted-header>

        <!-- or, if your proxy instead uses the "Forwarded" header -->
        <framework:trusted-header>forwarded</framework:trusted-header>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework
        // the IP address (or range) of your proxy
        ->trustedProxies('192.0.0.1,10.0.0.0/8')
        // shortcut for private IP address ranges of your proxy
        ->trustedProxies('private_ranges')
        // trust *all* "X-Forwarded-*" headers (the ! prefix means to not trust those headers)
        ->trustedHeaders(['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix'])
        // or, if your proxy instead uses the "Forwarded" header
        ->trustedHeaders(['forwarded'])
    ;
};

The Request object has several Request::HEADER_* constants that control exactly which headers from your reverse proxy are trusted. The argument is a bit field, so you can also pass your own value (e.g. 0b00110).

1
2

# .env
TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8

1
2
3
4

# config/packages/framework.yaml
framework:
    # ...
    trusted_proxies: '%env(TRUSTED_PROXIES)%'

But what if the IP of my Reverse Proxy Changes Constantly!

Some reverse proxies (like AWS Elastic Load Balancing) don't have a static IP address or even a range that you can target with the CIDR notation. In this case, you'll need to - very carefully - trust all proxies.

1. Configure your web server(s) to not respond to traffic from any clients other than your load balancers. For AWS, this can be done with security groups.

2. Once you've guaranteed that traffic will only come from your trusted reverse proxies, configure Symfony to always trust incoming request:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

   # config/packages/framework.yaml
   framework:
       # ...
       # trust *all* requests (the 'REMOTE_ADDR' string is replaced at
       # runtime by $_SERVER['REMOTE_ADDR'])
       trusted_proxies: '127.0.0.1,REMOTE_ADDR'
   
       # you can also use the 'PRIVATE_SUBNETS' string, which is replaced at
       # runtime by the IpUtils::PRIVATE_SUBNETS constant
       # trusted_proxies: '127.0.0.1,PRIVATE_SUBNETS'

That's it! It's critical that you prevent traffic from all non-trusted sources. If you allow outside traffic, they could "spoof" their true IP address and other information.

If you are also using a reverse proxy on top of your load balancer (e.g. CloudFront), calling $request->server->get('REMOTE_ADDR') won't be enough, as it will only trust the node sitting directly above your application (in this case your load balancer). You also need to append the IP addresses or ranges of any additional proxy (e.g. CloudFront IP ranges) to the array of trusted proxies.

Reverse proxy in a subpath / subfolder

If your Symfony application runs behind a reverse proxy and it's served in a subpath/subfolder, Symfony might generate incorrect URLs that ignore the subpath/subfolder of the reverse proxy.

To fix this, you need to pass the subpath/subfolder route prefix of the reverse proxy to Symfony by setting the X-Forwarded-Prefix header. The header can normally be configured in your reverse proxy configuration. Configure X-Forwarded-Prefix as trusted header to be able to use this feature.

The X-Forwarded-Prefix is used by Symfony to prefix the base URL of request objects, which is used to generate absolute paths and URLs in Symfony applications. Without the header, the base URL would be only determined based on the configuration of the web server running Symfony, which leads to incorrect paths/URLs, when the application is served under a subpath/subfolder by a reverse proxy.

For example if your Symfony application is directly served under a URL like https://symfony.tld/ and you would like to use a reverse proxy to serve the application under https://public.tld/app/, you would need to set the X-Forwarded-Prefix header to /app/ in your reverse proxy configuration. Without the header, Symfony would generate URLs based on its server base URL (e.g. /my/route) instead of the correct /app/my/route, which is required to access the route via the reverse proxy.

The header can be different for each reverse proxy, so that access via different reverse proxies served under different subpaths/subfolders can be handled correctly.

Custom Headers When Using a Reverse Proxy

Some reverse proxies (like CloudFront with CloudFront-Forwarded-Proto) may force you to use a custom header. For instance you have Custom-Forwarded-Proto instead of X-Forwarded-Proto.

In this case, you'll need to set the header X-Forwarded-Proto with the value of Custom-Forwarded-Proto early enough in your application, i.e. before handling the request:

1
2
3
4
5
6

// public/index.php

// ...
$_SERVER['HTTP_X_FORWARDED_PROTO'] = $_SERVER['HTTP_CUSTOM_FORWARDED_PROTO'];
// ...
$response = $kernel->handle($request);

Overriding Configuration Behind Hidden SSL Termination

Some cloud setups (like running a Docker container with the "Web App for Containers" in Microsoft Azure) do SSL termination and contact your web server over HTTP, but do not change the remote address nor set the X-Forwarded-* headers. This means the trusted proxy feature of Symfony can't help you.

Once you made sure your server is only reachable through the cloud proxy over HTTPS and not through HTTP, you can override the information your web server sends to PHP. For Nginx, this could look like this:

1
2
3
4
5
6
7

location ~ ^/index\.php$ {
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi.conf;
    # Lie to Symfony about the protocol and port so that it generates the correct HTTPS URLs
    fastcgi_param SERVER_PORT "443";
    fastcgi_param HTTPS "on";
}