Headers

The Headers middleware manages the headers of requests and responses.

By default, the following headers are automatically added when proxying requests:

Property	HTTP Header
Client's IP	X-Forwarded-For, X-Real-Ip
Host	X-Forwarded-Host
Port	X-Forwarded-Port
Protocol	X-Forwarded-Proto
Proxy Server's Hostname	X-Forwarded-Server

Configuration Examples

Adding Headers to the Request and the Response

The following example adds the X-Script-Name header to the proxied request and the X-Custom-Response-Header header to the response

Structured (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test"
        customResponseHeaders:
          X-Custom-Response-Header: "value"

Structured (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test"
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "value"

Labels

labels:
  - "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"

Tags

{
  //...
  "Tags": [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test"
    customResponseHeaders:
      X-Custom-Response-Header: "value"

Adding and Removing Headers

In the following example, requests are proxied with an extra X-Script-Name header while their X-Custom-Request-Header header gets stripped, and responses are stripped of their X-Custom-Response-Header header.

Structured (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test" # Adds
          X-Custom-Request-Header: "" # Removes
        customResponseHeaders:
          X-Custom-Response-Header: "" # Removes

Structured (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test" # Adds
        X-Custom-Request-Header = "" # Removes
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "" # Removes

Labels

labels:
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header="
  - "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header=",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test" # Adds
      X-Custom-Request-Header: "" # Removes
    customResponseHeaders:
      X-Custom-Response-Header: "" # Removes

Using Security Headers

Security-related headers (HSTS headers, Browser XSS filter, etc) can be managed similarly to custom headers as shown above. This functionality makes it possible to easily use security features by adding headers.

Structured (YAML)

http:
  middlewares:
    testHeader:
      headers:
        frameDeny: true
        browserXssFilter: true

Structured (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    frameDeny = true
    browserXssFilter = true

Labels

labels:
  - "traefik.http.middlewares.testHeader.headers.framedeny=true"
  - "traefik.http.middlewares.testHeader.headers.browserxssfilter=true"

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.framedeny=true",
    "traefik.http.middlewares.testheader.headers.browserxssfilter=true"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    frameDeny: true
    browserXssFilter: true

CORS Headers

CORS (Cross-Origin Resource Sharing) headers can be added and configured in a manner similar to the custom headers above. This functionality allows for more advanced security features to quickly be set. If CORS headers are set, then the middleware does not pass preflight requests to any service, instead the response will be generated and sent back to the client directly.
Please note that the example below is by no means authoritative or exhaustive, and should not be used as is for production.

Structured (YAML)

http:
  middlewares:
    testHeader:
      headers:
        accessControlAllowMethods:
          - GET
          - OPTIONS
          - PUT
        accessControlAllowHeaders: "*"
        accessControlAllowOriginList:
          - https://foo.bar.org
          - https://example.org
        accessControlMaxAge: 100
        addVaryHeader: true

Structured (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    accessControlAllowMethods = ["GET", "OPTIONS", "PUT"]
    accessControlAllowHeaders = [ "*" ]
    accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
    accessControlMaxAge = 100
    addVaryHeader = true

Labels

labels:
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*"
  - "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
  - "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
  - "traefik.http.middlewares.testheader.headers.addvaryheader=true"

Tags

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT",
     "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*",
    "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org",
    "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100",
    "traefik.http.middlewares.testheader.headers.addvaryheader=true"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    accessControlAllowMethods:
      - "GET"
      - "OPTIONS"
      - "PUT"
    accessControlAllowHeaders:
      - "*"
    accessControlAllowOriginList:
      - "https://foo.bar.org"
      - "https://example.org"
    accessControlMaxAge: 100
    addVaryHeader: true

Configuration Options

Warning

Custom headers will overwrite existing headers if they have identical names.

The detailed documentation for security headers can be found in unrolled/secure.

Field	Description	Default	Required
customRequestHeaders	Lists the header names and values for requests.	[]	No
customResponseHeaders	Lists the header names and values for responses.	[]	No
accessControlAllowCredentials	Indicates if the request can include user credentials.	false	No
accessControlAllowHeaders	Specifies allowed request header names.	[]	No
accessControlAllowMethods	Specifies allowed request methods.	[]	No
accessControlAllowOriginList	Specifies allowed origins. More information here	[]	No
accessControlAllowOriginListRegex	Allows origins matching regex. More information here	[]	No
accessControlExposeHeaders	Specifies which headers are safe to expose to the API of a CORS API specification.	[]	No
accessControlMaxAge	Time (in seconds) to cache preflight requests.	0	No
addVaryHeader	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.	false	No
allowedHosts	Lists allowed domain names.	[]	No
hostsProxyHeaders	Specifies header keys for proxied hostname.	[]	No
sslProxyHeaders	Defines a set of header keys with associated values that would indicate a valid HTTPS request. It can be useful when using other proxies (example: "X-Forwarded-Proto": "https").	{}	No
stsSeconds	Max age for Strict-Transport-Security header.	0	No
stsIncludeSubdomains	If set to true, the includeSubDomains directive is appended to the Strict-Transport-Security header.	false	No
stsPreload	Adds preload flag to STS header.	false	No
forceSTSHeader	Adds STS header for HTTP connections.	false	No
frameDeny	Set frameDeny to true to add the X-Frame-Options header with the value of DENY.	false	No
customFrameOptionsValue	allows the X-Frame-Options header value to be set with a custom value. This overrides the FrameDeny option.	""	No
contentTypeNosniff	Set contentTypeNosniff to true to add the X-Content-Type-Options header with the value nosniff.	false	No
browserXssFilter	Set browserXssFilter to true to add the X-XSS-Protection header with the value 1; mode=block.	false	No
customBrowserXSSValue	allows the X-XSS-Protection header value to be set with a custom value. This overrides the BrowserXssFilter option.	false	No
contentSecurityPolicy	allows the Content-Security-Policy header value to be set with a custom value.	false	No
contentSecurityPolicyReportOnly	allows the Content-Security-Policy-Report-Only header value to be set with a custom value.	""	No
publicKey	Implements HPKP for certificate pinning.	""	No
referrerPolicy	Controls forwarding of Referer header.	""	No
permissionsPolicy	allows sites to control browser features.	""	No
isDevelopment	Set true when developing to mitigate the unwanted effects of the AllowedHosts, SSL, and STS options. Usually testing takes place using HTTP, not HTTPS, and on localhost, not your production domain.	false	No

accessControlAllowOriginList

The accessControlAllowOriginList indicates whether a resource can be shared by returning different values.

A wildcard origin * can also be configured, and matches all requests. If this value is set by a backend service, it will be overwritten by Traefik.

This value can contain a list of allowed origins.

More information including how to use the settings can be found at:

• Mozilla.org
• w3
• IETF

Traefik no longer supports the null value, as it is no longer recommended as a return value.

accessControlAllowOriginListRegex

The accessControlAllowOriginListRegex option is the counterpart of the accessControlAllowOriginList option with regular expressions instead of origin values. It allows all origins that contain any match of a regular expression in the accessControlAllowOriginList.

Tip

Regular expressions and replacements can be tested using online tools such as Go Playground or the Regex101.

When defining a regular expression within YAML, any escaped character needs to be escaped twice: example\.com needs to be written as example\\.com.

---

Using Traefik OSS in Production?

If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.

• Watch our API Gateway Demo Video
• Request 24/7/365 OSS Support

Adding API Gateway capabilities to Traefik OSS is fast and seamless. There's no rip and replace and all configurations remain intact. See it in action via this short video.