Skip to content

DOC Update X-Forwarded-Proto header documentation #892

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GuySartorelli merged 1 commit into from
Mar 26, 2026
Merged

DOC Update X-Forwarded-Proto header documentation #892

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions en/02_Developer_Guides/08_Performance/02_HTTP_Cache_Headers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,11 +228,24 @@ By default, Silverstripe CMS will output a `Vary` header with the following cont
Vary: X-Forwarded-Protocol
```

To change the value of the `Vary` header, you can change this value by specifying the header in configuration.
> [!IMPORTANT]
> For historical reasons the default vary header is `X-Forwarded-Protocol` instead of the standard `X-Forwarded-Proto`.
> If you are using a CDN or proxy which relies on `X-Forwarded-Proto` to determine the protocol of the request, you should change the default vary header to `X-Forwarded-Proto` to ensure that cached content is correctly served over both HTTP and HTTPS.

To change the value of the `Vary` header, you can change this value by disabling the old header and specifying the new header in configuration:

```yml
SilverStripe\Control\HTTP:
vary: ""
SilverStripe\Control\Middleware\HTTPCacheControlMiddleware:
defaultVary:
X-Forwarded-Protocol: false
X-Forwarded-Proto: true
```

You can also remove the default `Vary` header value by setting it to `null`:

```yml
SilverStripe\Control\Middleware\HTTPCacheControlMiddleware:
defaultVary: null
```

Note that if you use `Director::is_ajax()` on cached pages
Expand Down
18 changes: 13 additions & 5 deletions en/02_Developer_Guides/09_Security/05_Secure_Coding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -762,13 +762,21 @@ If you wish to change the headers that are used to find the proxy information, y
`TrustedProxyMiddleware` service:

```yml
SilverStripe\Control\TrustedProxyMiddleware:
Copy link
Copy Markdown
Member Author

@emteknetnz emteknetnz Mar 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was also wrong, have updated

Note has a different syntax to the HTTPCacheControlMiddleware example above as we set the Injector config here meaning there's no need to 'unset' the default values like we do above setting HTTPCacheControlMiddleware.defaultVary.X-Forwarded-Protocol: false -- HTTPCacheControlMiddleware lacks the getDefaultVary() and setDefaultVary() methods so we need to use that approach above

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.
Expand Down
Loading