DOC Update X-Forwarded-Proto header documentation

en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md

@@ -222,21 +222,37 @@ HTTP::register_modification_date('2014-10-10');
 
 A `Vary` header tells caches which aspects of the response should be considered
 when calculating a cache key, usually in addition to the full URL.
-By default, Silverstripe CMS will output a `Vary` header with the following content:
+By default, Silverstripe CMS sets the `Vary` header to `X-Forwarded-Proto`. This ensures that caches
+(such as CDNs and reverse proxies) create separate cache entries for HTTP and HTTPS requests,
+preventing HTTPS users from being served a response originally cached for HTTP (or vice versa).
 
-```text
-Vary: X-Forwarded-Protocol
-```
+> [!NOTE]
+> Prior to Silverstripe CMS 5.4, the default `Vary` header was set to the non-standard
+> `X-Forwarded-Protocol`. This has been updated to the standard `X-Forwarded-Proto` header, which is
+> used by all major reverse proxies including Nginx, Apache, AWS ALB, and Cloudflare.
 
-To change the value of the `Vary` header, you can change this value by specifying the header in configuration.
+If your site is HTTPS-only (as recommended), varying by protocol is harmless but
+unnecessary since all requests will have the same protocol value. You can disable it:
 
 ```yml
-SilverStripe\Control\HTTP:
-  vary: ""
+SilverStripe\Control\Middleware\HTTPCacheControlMiddleware:
+  defaultVary: null
 ```
 
-Note that if you use `Director::is_ajax()` on cached pages
-then you should add `X-Requested-With` to the vary header.
+If you serve both HTTP and HTTPS with different content, the default `X-Forwarded-Proto` variance
+is important and should be left in place. Note that this only has an effect when your reverse proxy
+sets the `X-Forwarded-Proto` header and the application is configured to trust it via
+[`TrustedProxyMiddleware`](api:SilverStripe\Control\Middleware\TrustedProxyMiddleware).
+
+You can also add additional headers to vary on. For example, if you use `Director::is_ajax()` on
+cached pages then you should add `X-Requested-With`:
+
+```yml
+SilverStripe\Control\Middleware\HTTPCacheControlMiddleware:
+  defaultVary:
+    X-Forwarded-Proto: true
+    X-Requested-With: true
+```
 
 ## Testing
 

en/02_Developer_Guides/09_Security/05_Secure_Coding.md

@@ -756,19 +756,29 @@ If there is no proxy server, 'none' can be used to explicitly distrust all clien
 If only trusted servers will make requests then you can use '*' to trust all clients.
 Otherwise a comma separated list of individual IP addresses (or subnets in CIDR notation) should be declared.
 
-At the same time, you'll also need to define which headers you trust from these proxy IPs. Since there are multiple ways through which proxies can pass through HTTP information on the original hostname, IP and protocol, these values need to be adjusted for your specific proxy. The header names match their equivalent `$_SERVER` values.
+At the same time, you'll also need to define which headers you trust from these proxy IPs. This is only relevant when
+`TrustedProxyMiddleware` is enabled with trusted proxy IPs configured - never trust forwarded headers from arbitrary
+clients. Since there are multiple ways through which proxies can pass through HTTP information on the original
+hostname, IP and protocol, these values need to be adjusted for your specific proxy. The header names match their
+equivalent `$_SERVER` values.
 
 If you wish to change the headers that are used to find the proxy information, you should reconfigure the
 `TrustedProxyMiddleware` service:
 
 ```yml
-SilverStripe\Control\TrustedProxyMiddleware:
-  properties:
-    ProxyHostHeaders: X-Forwarded-Host
-    ProxySchemeHeaders: X-Forwarded-Protocol
-    ProxyIPHeaders: X-Forwarded-Ip
+SilverStripe\Core\Injector\Injector:
+  SilverStripe\Control\Middleware\TrustedProxyMiddleware:
+    properties:
+      ProxyHostHeaders: X-Forwarded-Host
+      ProxySchemeHeaders:
+        - X-Forwarded-Proto
+        - X-Forwarded-Protocol
+      ProxyIPHeaders: X-Forwarded-Ip
 ```
 
+Scheme headers are checked in order, so `X-Forwarded-Proto` is preferred with `X-Forwarded-Protocol` as a legacy
+fallback. If neither header is present, Silverstripe CMS falls back to the standard HTTPS and SSL server variables.
+
 ## TLS (aka SSL aka HTTPS)
 
 Silverstripe CMS recommends the use of TLS (HTTPS) for your application. You can configure this by setting the `ForceSSL` property on the [`CanonicalURLMiddleware`](api:SilverStripe\Control\Middleware\CanonicalURLMiddleware) singleton.