Skip to main content
The system node contains basic technical configurations of the shop. These control the system behaviour at the infrastructure level — independently of shop content. The configuration is done in the Admin Interface in the “Storefront API” area.

​
system* - Basic structure

The basic structure of the system node is shown below: 
{
  "system": {
    "trustedProxies": { ... }
  }
}
Parameter description
ParameterDescription
trustedProxiesConfiguration of the trusted proxy servers from which the X-Forwarded-For HTTP header is accepted.

​
system.trustedProxies - Trusted proxy servers

In some setups the shop is not directly reachable over the internet but instead through an upstream server. This is the case, for example, when an agency hosts the shop frontend on its own infrastructure. In this case, the shop does not see the IP address of the end customer for incoming requests, but only that of the agency server. This is problematic as soon as the shop has to block IP addresses, for example for too many failed login attempts or suspicious payment processes. Since all requests in this case come from the same agency server IP, a block would make the shop inaccessible for all customers. Why is an allowlist necessary?
The shop must not accept the X-Forwarded-For header from arbitrary servers. An attacker could set this header themselves and supply a forged IP address to the shop, thereby bypassing IP-based protection mechanisms. For this reason, an allowlist is maintained via trustedProxies. Only servers whose IP address is entered there may set the X-Forwarded-For header. From all other servers, this header is ignored.
If the shop is run behind a proxy server and trustedProxies is not configured correctly, IP blocks may affect the entire proxy IP and thus block the shop for all customers. In this case, ensure that the proxy server forwards the real client IP via X-Forwarded-For and that its IP is entered here.
Example configuration for system.trustedProxies 
{
  "addresses": [
    "13.196.200.101",
    "13.196.0.0/16",
    "1234:5678:9abc:def0::1",
    "1234:5678:9abc:def0::/64"
  ]
}
Parameter description
ParameterTypeDescription
addresseslist (string)List of IP addresses or IP subnets from which the X-Forwarded-For header is accepted.
Supported are individual IPv4 and IPv6 addresses as well as CIDR subnets.

Default: []
Supported IP formats
FormatExampleDescription
IPv4 address13.196.200.101A single, explicit IPv4 address.
IPv4 subnet (CIDR)13.196.0.0/16All addresses in the range
13.196.0.0 - 13.196.255.255.
IPv6 address1234:5678:9abc:def0::1A single, explicit IPv6 address.
IPv6 subnet (CIDR)1234:5678:9abc:def0::/64An IPv6 subnet in CIDR notation.
Subnets in CIDR notation are especially useful when an upstream server uses a dynamic IP from a known, fixed address range.