traefik/docs/content/middlewares/headers.md

421 lines
13 KiB
Markdown
Raw Normal View History

# Headers
Adding Headers to the Request / Response
{: .subtitle }
![Headers](../assets/img/middleware/headers.png)
The Headers middleware can manage the requests/responses headers.
## Configuration Examples
### Adding Headers to the Request and the Response
Add the `X-Script-Name` header to the proxied request and the `X-Custom-Response-Header` to the response
2019-03-29 11:34:05 +00:00
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"
2019-04-02 08:40:04 +00:00
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testHeader
spec:
headers:
customRequestHeaders:
2019-04-02 08:40:04 +00:00
X-Script-Name: "test"
customResponseHeaders:
2019-07-22 07:58:04 +00:00
X-Custom-Response-Header: "value"
2019-03-29 11:34:05 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```json tab="Marathon"
"labels": {
2019-07-01 09:30:05 +00:00
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name": "test",
2019-07-22 07:58:04 +00:00
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header": "value"
}
```
2019-04-08 15:14:08 +00:00
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-03-29 11:34:05 +00:00
[http.middlewares]
[http.middlewares.testHeader.headers]
2019-07-01 09:30:05 +00:00
[http.middlewares.testHeader.headers.customRequestHeaders]
2019-03-29 11:34:05 +00:00
X-Script-Name = "test"
2019-07-01 09:30:05 +00:00
[http.middlewares.testHeader.headers.customResponseHeaders]
2019-07-22 07:58:04 +00:00
X-Custom-Response-Header = "value"
```
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test"
customResponseHeaders:
X-Custom-Response-Header: "value"
2019-03-29 11:34:05 +00:00
```
### Adding and Removing Headers
2019-04-05 13:18:04 +00:00
`X-Script-Name` header added to the proxied request, the `X-Custom-Request-Header` header removed from the request,
and the `X-Custom-Response-Header` header removed from the response.
2019-09-03 16:02:05 +00:00
Please note that it is not possible to remove headers through the use of labels (Docker, Rancher, Marathon, ...) for now.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
```
2019-04-02 08:40:04 +00:00
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testHeader
spec:
headers:
customRequestHeaders:
2019-04-05 13:18:04 +00:00
X-Script-Name: "test" # Adds
X-Custom-Request-Header: "" # Removes
customResponseHeaders:
2019-04-05 13:18:04 +00:00
X-Custom-Response-Header: "" # Removes
2019-04-02 08:40:04 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
```
2019-04-24 15:44:04 +00:00
```json tab="Marathon"
"labels": {
2019-07-01 09:30:05 +00:00
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name": "test",
2019-04-24 15:44:04 +00:00
}
2019-04-08 15:14:08 +00:00
```
2019-09-03 16:02:05 +00:00
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-04-02 08:40:04 +00:00
[http.middlewares]
[http.middlewares.testHeader.headers]
2019-07-01 09:30:05 +00:00
[http.middlewares.testHeader.headers.customRequestHeaders]
2019-04-05 13:18:04 +00:00
X-Script-Name = "test" # Adds
X-Custom-Request-Header = "" # Removes
2019-07-01 09:30:05 +00:00
[http.middlewares.testHeader.headers.customResponseHeaders]
2019-04-05 13:18:04 +00:00
X-Custom-Response-Header = "" # Removes
2019-04-02 08:40:04 +00:00
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test" # Adds
X-Custom-Request-Header: "" # Removes
customResponseHeaders:
X-Custom-Response-Header: "" # Removes
```
### Using Security Headers
2019-09-03 16:02:05 +00:00
Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc) can be added and configured in a manner similar to the custom headers above.
This functionality allows for some easy security features to quickly be set.
2019-04-02 08:40:04 +00:00
```yaml tab="Docker"
labels:
2019-07-01 09:30:05 +00:00
- "traefik.http.middlewares.testHeader.headers.framedeny=true"
- "traefik.http.middlewares.testHeader.headers.sslredirect=true"
2019-04-02 08:40:04 +00:00
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testHeader
spec:
headers:
frameDeny: "true"
sslRedirect: "true"
2019-04-02 08:40:04 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.testheader.headers.framedeny=true"
- "traefik.http.middlewares.testheader.headers.sslredirect=true"
```
2019-04-24 15:44:04 +00:00
```json tab="Marathon"
"labels": {
2019-07-01 09:30:05 +00:00
"traefik.http.middlewares.testheader.headers.framedeny": "true",
"traefik.http.middlewares.testheader.headers.sslredirect": "true"
2019-04-24 15:44:04 +00:00
}
```
2019-09-03 16:02:05 +00:00
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.testheader.headers.framedeny=true"
- "traefik.http.middlewares.testheader.headers.sslredirect=true"
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-04-02 08:40:04 +00:00
[http.middlewares]
[http.middlewares.testHeader.headers]
2019-10-23 09:48:05 +00:00
frameDeny = true
sslRedirect = true
2019-04-02 08:40:04 +00:00
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
2019-10-23 09:48:05 +00:00
frameDeny: true
sslRedirect: true
2019-07-22 07:58:04 +00:00
```
2019-04-02 08:40:04 +00:00
### CORS Headers
2019-09-03 16:02:05 +00:00
CORS (Cross-Origin Resource Sharing) headers can be added and configured in a manner similar to the custom headers above.
2019-04-02 08:40:04 +00:00
This functionality allows for more advanced security features to quickly be set.
```yaml tab="Docker"
labels:
2019-07-01 09:30:05 +00:00
- "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
- "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
2019-07-01 09:30:05 +00:00
- "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
2019-04-02 08:40:04 +00:00
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testHeader
spec:
headers:
2019-07-01 09:30:05 +00:00
accessControlAllowMethods:
2019-04-02 08:40:04 +00:00
- "GET"
- "OPTIONS"
- "PUT"
accessControlAllowOriginList:
- "https://foo.bar.org"
- "https://example.org"
2019-07-01 09:30:05 +00:00
accessControlMaxAge: 100
addVaryHeader: "true"
2019-04-02 08:40:04 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
- "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
2019-10-15 15:34:08 +00:00
- "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
```
2019-04-24 15:44:04 +00:00
```json tab="Marathon"
"labels": {
2019-07-01 09:30:05 +00:00
"traefik.http.middlewares.testheader.headers.accesscontrolallowmethods": "GET,OPTIONS,PUT",
"traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist": "https://foo.bar.org,https://example.org",
2019-07-01 09:30:05 +00:00
"traefik.http.middlewares.testheader.headers.accesscontrolmaxage": "100",
"traefik.http.middlewares.testheader.headers.addvaryheader": "true"
2019-04-24 15:44:04 +00:00
}
```
2019-09-03 16:02:05 +00:00
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
- "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
2019-09-03 16:02:05 +00:00
- "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
2019-04-02 08:40:04 +00:00
[http.middlewares]
[http.middlewares.testHeader.headers]
2019-07-01 09:30:05 +00:00
accessControlAllowMethods= ["GET", "OPTIONS", "PUT"]
accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
2019-07-01 09:30:05 +00:00
accessControlMaxAge = 100
addVaryHeader = true
2019-04-02 08:40:04 +00:00
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
2019-10-02 14:32:05 +00:00
accessControlAllowMethods:
2019-09-23 15:00:06 +00:00
- GET
- OPTIONS
- PUT
accessControlAllowOriginList:
- https://foo.bar.org
- https://example.org
2019-07-22 07:58:04 +00:00
accessControlMaxAge: 100
addVaryHeader: true
```
## Configuration Options
### General
!!! warning
If the custom header name is the same as one header name of the request or response, it will be replaced.
2019-09-23 12:32:04 +00:00
!!! note ""
The detailed documentation for the security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
2019-04-03 12:32:04 +00:00
### `customRequestHeaders`
The `customRequestHeaders` option lists the Header names and values to apply to the request.
2019-04-03 12:32:04 +00:00
### `customResponseHeaders`
2019-04-02 08:40:04 +00:00
The `customResponseHeaders` option lists the Header names and values to apply to the response.
2019-04-03 12:32:04 +00:00
### `accessControlAllowCredentials`
2019-04-02 08:40:04 +00:00
The `accessControlAllowCredentials` indicates whether the request can include user credentials.
2019-04-03 12:32:04 +00:00
### `accessControlAllowHeaders`
2019-04-02 08:40:04 +00:00
The `accessControlAllowHeaders` indicates which header field names can be used as part of the request.
2019-04-03 12:32:04 +00:00
### `accessControlAllowMethods`
2019-04-02 08:40:04 +00:00
The `accessControlAllowMethods` indicates which methods can be used during requests.
### `accessControlAllowOriginList`
2019-04-02 08:40:04 +00:00
The `accessControlAllowOriginList` indicates whether a resource can be shared by returning different values.
2019-04-02 08:40:04 +00:00
A wildcard origin `*` can also be configured, and will match all requests.
If this value is set by a backend server, it will be overwritten by Traefik
This value can contains a list of allowed origins.
More information including how to use the settings can be found on:
- [Mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
- [w3](https://www.w3.org/TR/cors/#access-control-allow-origin-response-header)
- [IETF](https://tools.ietf.org/html/rfc6454#section-7.1)
Traefik no longer supports the null value, as it is [no longer recommended as a return value](https://w3c.github.io/webappsec-cors-for-developers/#avoid-returning-access-control-allow-origin-null).
2019-04-02 08:40:04 +00:00
2019-04-03 12:32:04 +00:00
### `accessControlExposeHeaders`
2019-04-02 08:40:04 +00:00
The `accessControlExposeHeaders` indicates which headers are safe to expose to the api of a CORS API specification.
2019-04-03 12:32:04 +00:00
### `accessControlMaxAge`
2019-04-02 08:40:04 +00:00
2020-04-14 16:04:04 +00:00
The `accessControlMaxAge` indicates how long (in seconds) a preflight request can be cached.
2019-04-02 08:40:04 +00:00
2019-04-03 12:32:04 +00:00
### `addVaryHeader`
2019-04-02 08:40:04 +00:00
The `addVaryHeader` is used in conjunction with `accessControlAllowOriginList` to determine whether the vary header should be added or modified to demonstrate that server responses can differ based on the value of the origin header.
2019-04-02 08:40:04 +00:00
2019-04-03 12:32:04 +00:00
### `allowedHosts`
The `allowedHosts` option lists fully qualified domain names that are allowed.
2019-04-03 12:32:04 +00:00
### `hostsProxyHeaders`
The `hostsProxyHeaders` option is a set of header keys that may hold a proxied hostname value for the request.
2019-04-03 12:32:04 +00:00
### `sslRedirect`
The `sslRedirect` is set to true, then only allow https requests.
2019-04-03 12:32:04 +00:00
### `sslTemporaryRedirect`
Set the `sslTemporaryRedirect` to `true` to force an SSL redirection using a 302 (instead of a 301).
2019-04-03 12:32:04 +00:00
### `sslHost`
2019-07-01 09:30:05 +00:00
The `sslHost` option is the host name that is used to redirect http requests to https.
2019-04-03 12:32:04 +00:00
### `sslProxyHeaders`
2019-07-01 09:30:05 +00:00
The `sslProxyHeaders` option is set of header keys with associated values that would indicate a valid https request.
Useful when using other proxies with header like: `"X-Forwarded-Proto": "https"`.
2019-04-03 12:32:04 +00:00
### `sslForceHost`
Set `sslForceHost` to true and set SSLHost to forced requests to use `SSLHost` even the ones that are already using SSL.
2019-04-03 12:32:04 +00:00
### `stsSeconds`
2019-07-01 09:30:05 +00:00
The `stsSeconds` is the max-age of the Strict-Transport-Security header.
If set to 0, would NOT include the header.
2019-04-03 12:32:04 +00:00
### `stsIncludeSubdomains`
2019-09-25 14:50:16 +00:00
The `stsIncludeSubdomains` is set to true, the `includeSubDomains` directive will be appended to the Strict-Transport-Security header.
2019-04-03 12:32:04 +00:00
### `stsPreload`
2019-07-01 09:30:05 +00:00
Set `stsPreload` to true to have the `preload` flag appended to the Strict-Transport-Security header.
2019-04-03 12:32:04 +00:00
### `forceSTSHeader`
2019-07-01 09:30:05 +00:00
Set `forceSTSHeader` to true, to add the STS header even when the connection is HTTP.
2019-04-03 12:32:04 +00:00
### `frameDeny`
Set `frameDeny` to true to add the `X-Frame-Options` header with the value of `DENY`.
2019-04-03 12:32:04 +00:00
### `customFrameOptionsValue`
2019-07-01 09:30:05 +00:00
The `customFrameOptionsValue` allows the `X-Frame-Options` header value to be set with a custom value.
This overrides the FrameDeny option.
2019-04-03 12:32:04 +00:00
### `contentTypeNosniff`
Set `contentTypeNosniff` to true to add the `X-Content-Type-Options` header with the value `nosniff`.
2019-04-03 12:32:04 +00:00
### `browserXssFilter`
2019-07-01 09:30:05 +00:00
Set `browserXssFilter` to true to add the `X-XSS-Protection` header with the value `1; mode=block`.
2019-04-03 12:32:04 +00:00
### `customBrowserXSSValue`
2019-07-01 09:30:05 +00:00
The `customBrowserXssValue` option allows the `X-XSS-Protection` header value to be set with a custom value.
This overrides the BrowserXssFilter option.
2019-04-03 12:32:04 +00:00
### `contentSecurityPolicy`
The `contentSecurityPolicy` option allows the `Content-Security-Policy` header value to be set with a custom value.
2019-04-03 12:32:04 +00:00
### `publicKey`
The `publicKey` implements HPKP to prevent MITM attacks with forged certificates.
2019-04-03 12:32:04 +00:00
### `referrerPolicy`
The `referrerPolicy` allows sites to control when browsers will pass the Referer header to other sites.
2019-07-29 14:12:05 +00:00
### `featurePolicy`
The `featurePolicy` allows sites to control browser features.
2019-04-03 12:32:04 +00:00
### `isDevelopment`
2019-07-01 09:30:05 +00:00
Set `isDevelopment` to true when developing.
The AllowedHosts, SSL, and STS options can cause some unwanted effects.
Usually testing happens on http, not https, and on localhost, not your production domain.
If you would like your development environment to mimic production with complete Host blocking, SSL redirects, and STS headers, leave this as false.