Running TYPO3 behind a reverse proxy or load balancer

When running TYPO3 behind a reverse proxy or load balancer in a production environment, you may encounter issues that are difficult to reproduce in a local setup.

Please refer to the documentation of that server on what exact settings are needed.

Table of contents

Proxy and reverse proxy

Proxy

A proxy server acts as an intermediary between client devices (such as web browsers) and the internet. It processes requests from clients seeking resources from other servers. The primary use cases include:

  • Privacy and anonymity by masking client IP addresses
  • Access control and content filtering
  • Caching frequently requested resources
  • Bypassing geographic restrictions

Difference between proxy and reverse proxy

While both types act as intermediaries, they serve different purposes:

  • Forward Proxy (Standard Proxy):

    • Sits in front of clients
    • Helps clients access external resources
    • Primarily client-focused
    • Masks client identity from servers

  • Reverse Proxy:

    • Sits in front of servers
    • Handles incoming requests to backend servers
    • Server-focused
    • Masks server identity from clients
    • Influences SSL/TLS termination and security

Choosing the right kind of setup involving proxies is something that falls into the domain of your TYPO3 project's DevOps decissions. https://en.wikipedia.org/wiki/Reverse_proxy and https://en.wikipedia.org/wiki/Proxy_server descripe further key factors in depth.

While operating a forward proxy requires virtually no TYPO3-specific configuration, using a Reverse Proxy will require you to configure this integration (additionally to the specific proxy server configuration, like taking care of SSL/TLS termination):

Benefits of a reverse proxy

Implementing a reverse proxy with TYPO3 can offer several advantages, depending on its type and configuration. The following list highlights possible (but not necessary) factors:

  1. Load Balancing:

    • Distributes incoming traffic across multiple TYPO3 instances
    • Ensures high availability and optimal resource utilization

  2. Enhanced Security:

    • Acts as a shield for backend TYPO3 servers
    • Prevents direct access to backend infrastructure
    • Provides additional layer for DDoS protection, however, DDoS protection is a very complicated topic, and should be handled by experienced network engineers.

  3. SSL/TLS Termination:

    • Handles HTTPS encryption/decryption
    • Reduces computational load on backend TYPO3 servers

  4. Caching:

    • Caches static content
    • Reduces load on TYPO3 backend servers
    • Improves response times

Importance of protocol detection

TYPO3 needs to accurately determine whether the original client connection was HTTPS for several critical system functions. This information affects multiple core functionalities:

Security features

  • Cookie Security: Determines whether secure cookies should be set
  • Form Security: Influences CSRF token handling and form security measures
  • Environment Detection: Powers Environment::isHttps() checks

URL generation

  • Link Building: Affects how the LinkBuilder and UriBuilder generate URLs
  • Site Generator: Influences the SiteGenerator behavior
  • Protocol Selection: Determines whether URLs are generated with http:// or https://
  • Redirect Handling: Controls whether redirects point to HTTP or HTTPS URLs

Accurate protocol detection is crucial for maintaining security standards and ensuring proper functionality across the TYPO3 installation. Incorrect protocol detection can lead to:

  • Security vulnerabilities due to insecure cookie handling
  • Mixed content warnings in browsers
  • Broken functionality due to incorrect redirect chains
  • Potential security token validation issues

HTTPS detection and configuration

TYPO3 cannot inherently determine whether the original client connection was HTTP or HTTPS when operating behind a reverse proxy. This is because TYPO3 only sees the connection between itself and the reverse proxy, which is typically HTTP and often configured with "HTTPS=on" (e.g., via .htaccess).

  • If the reverse proxy exclusively handles HTTPS connections:

    • Add the proxy's IP address to reverseProxySSL
    • Example: $GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxySSL'] = '192.0.2.1';

  • If the reverse proxy handles both HTTP and HTTPS:

    • Add the proxy's IP address to reverseProxyIP
    • TYPO3 will then rely on the proxy's headers (typically X-Forwarded-Proto) to determine the protocol
    • Example: $GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] = '192.0.2.1';

Protocol detection fallback

TYPO3 implements a hierarchical approach to detect secure connections:

  1. First, checks reverseProxySSL configuration
  2. If using reverseProxyIP, evaluates the X-Forwarded-Proto header (since TYPO3 13.4)
  3. If no X-Forwarded-Proto header is present, TYPO3 falls back to checking various other HTTP headers and server configuration settings to determine the connection security status

This multi-layered approach ensures maximum compatibility with different reverse proxy configurations while maintaining security awareness in the application.

Configuring TYPO3 to trust a reverse proxy

TYPO3 must be explicitly configured to recognize and trust reverse proxy headers and IP addresses.

For example, add the following lines to config/system/additional.php:

config/system/additional.php 
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] = '192.0.2.1,192.168.0.0/16';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxySSL'] = '192.0.2.1,192.168.0.0/16';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyHeaderMultiValue'] = 'first';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['trustedHostsPattern'] = '^(www\.)?example\.com$';
Copied!

If you deploy the config/system/additional.php or have it container in a custom Docker image you can, for example, use the Application Context to limit the reverse proxy settings to the production environment:

config/system/additional.php 
<?php

use TYPO3\CMS\Core\Core\Environment;

if (Environment::getContext()->isProduction()) {
    $customChanges = [
        // Database Credentials and other production settings
        'SYS' => [
            'reverseProxySSL' => '192.0.2.1,192.168.0.0/16',
        ],
    ];
    $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
}
Copied!

You can also use environment variables for configuration

In production environments, always use specific IP addresses or CIDR ranges rather than wildcards.

Omitting parts of the IPv4 address acts as a wildcard (for example 192.168 is equivalent to 192.168.*.*). However, using the equivalent CIDR notation (192.168.0.0/16) is the recommended and standardized approach.

Note that IPv6 addresses are supported only with CIDR notation, not wildcards.

Common problems when using a reverse proxy

TYPO3 installations behind an improperly configured reverse proxy may exhibit issues such as:

  • Exceptions such as \TYPO3\CMS\Core\Http\Security\MissingReferrerException
  • Redirects to the wrong scheme (http instead of https)
  • Backend login / Install tool login failures or redirect loops

These problems often point to missing or untrusted forwarded headers, or a mismatch between the trusted host settings and the actual domain used.