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:
-
Load Balancing:
- Distributes incoming traffic across multiple TYPO3 instances
- Ensures high availability and optimal resource utilization
-
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.
-
SSL/TLS Termination:
- Handles HTTPS encryption/decryption
- Reduces computational load on backend TYPO3 servers
-
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::
checksis Https ()
URL generation
- Link Building: Affects how the
Link
andBuilder Uri
generate URLsBuilder - Site Generator: Influences the
Site
behaviorGenerator - Protocol Selection: Determines whether URLs are generated
with
http://
orhttps://
- 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
reverse
Proxy SSL - Example:
$GLOBALS
['TYPO3_ CONF_ VARS'] ['SYS'] ['reverse Proxy SSL'] = '192. 0. 2. 1';
- Add the proxy's IP address to
-
If the reverse proxy handles both HTTP and HTTPS:
- Add the proxy's IP address to
reverse
Proxy IP - TYPO3 will then rely on the proxy's headers (typically X-Forwarded-Proto) to determine the protocol
- Example:
$GLOBALS
['TYPO3_ CONF_ VARS'] ['SYS'] ['reverse Proxy IP'] = '192. 0. 2. 1';
- Add the proxy's IP address to
Protocol detection fallback
TYPO3 implements a hierarchical approach to detect secure connections:
- First, checks
reverse
configurationProxy SSL - If using
reverse
, evaluates theProxy IP X-
header (since TYPO3 13.4)Forwarded- Proto - If no
X-
header is present, TYPO3 falls back to checking various other HTTP headers and server configuration settings to determine the connection security statusForwarded- Proto
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/
:
$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$';
If you deploy the config/
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:
<?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);
}
You can also use environment variables for configuration
See also
The following settings in
$GLOBALS
:
- reverseProxyIP
- reverseProxyHeaderMultiValue
- reverseProxyPrefix
- reverseProxyPrefixSSL
- trustedHostsPattern
The following article from the symfony docs might be helpful in determining the correct IP address or CIDR ranges: How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy.
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.
is
equivalent to 192.
). However, using the equivalent CIDR notation
(192.
) 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\ Missing Referrer Exception - Redirects to the wrong scheme (
http
instead ofhttps
) - 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.