ForwardAuth

The ForwardAuth middleware delegates authentication to an external service. If the service answers with a 2XX code, access is granted, and the original request is performed. Otherwise, the response from the authentication server is returned.

---

Configuration Example

Middleware Forward Authentication

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
  namespace: traefik
spec:
  forwardAuth:
    address: https://example.com/auth
    tls:
      certSecret: mytlscert

Forward-Auth Secret

apiVersion: v1
kind: Secret
metadata:
  name: mytlscert
  namespace: traefik
data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Field	Description	Default	Required
address	Authentication server address.	""	Yes
trustForwardHeader	Trust all X-Forwarded-* headers. The trustForwardHeader option is deprecated and will be removed in the next major version. More information here.	false	No
authResponseHeaders	List of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers.		No
authResponseHeadersRegex	Regex to match by the headers to copy from the authentication server response and set on forwarded request, after stripping all headers that match the regex. More information here.	""	No
authRequestHeaders	List of the headers to copy from the request to the authentication server. It allows filtering headers that should not be passed to the authentication server. If not set or empty, then all request headers are passed.		No
addAuthCookiesToResponse	List of cookies to copy from the authentication server to the response, replacing any existing conflicting cookie from the forwarded response. Please note that all backend cookies matching the configured list will not be added to the response.		No
forwardBody	Sends the request body to the authentication server. As the body is read inside Traefik Hub API Gateway before forwarding, this breaks streaming.	false	No
maxBodySize	Maximum body size (in bytes) forwarded to the authentication server. If the body is larger, the request is rejected with a 401. -1 disables the limit, which can have performance or security implications. More information here.	-1	No
maxResponseBodySize	Maximum response body size (in bytes) read from the authentication server. If the response body exceeds this limit, the request is rejected with a 401. -1 disables the limit, which can have performance or security implications. More information here.	-1	No
headerField	Defines a header field to store the authenticated user. More information here.		No
preserveLocationHeader	Forward the Location header to the client as-is instead of prefixing it with the domain name of the authentication server.	false	No
preserveRequestMethod	Preserve the original request method when forwarding the request to the authentication server.	false	No
authSigninURL	URL to redirect to when the authentication server returns 401 Unauthorized.	""	No
tls.caSecret	Secret that contains the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle.		No
tls.certSecret	Secret that contains both the private and public certificates used for the secure connection to the authentication server.		No
tls.insecureSkipVerify	During TLS connections, accepts any certificate presented by the server regardless of the hostnames it covers.	false	No

authResponseHeadersRegex

It allows partial matching of the regular expression against the header key.

The start of string (^) and end of string ($) anchors should be used to ensure a full match against the header key.

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.

maxBodySize

The maxBodySize option controls the maximum size of request bodies (in bytes) that are forwarded to the authentication server.

By default, maxBodySize is -1, meaning the request body size is unlimited. This has security and performance implications:

• Security risk: Attackers can send extremely large request bodies, potentially causing DoS attacks or memory exhaustion.
• Performance impact: Large request bodies consume memory and processing resources.
• Resource consumption: Unlimited body size can lead to unexpected resource usage patterns.

It is strongly recommended to set an appropriate maxBodySize value for your use case (for example, 1048576 for 1MB).

maxResponseBodySize

The maxResponseBodySize option defines the maximum allowed response body size (in bytes) returned by the authentication server. If the response body exceeds the configured limit, the request is rejected with a 401 Unauthorized status. If left unset (or set to -1), the response body size is unrestricted, which can have performance or security implications such as DoS attacks and memory exhaustion.

trustForwardHeader

Deprecated

The trustForwardHeader option is deprecated and will be removed in the next major version.

Configure the trusted IPs at the EntryPoint level using forwardedHeaders.trustedIPs, and set trustForwardHeader to true on this middleware.

With this setup, the EntryPoint is responsible for sanitizing incoming X-Forwarded-* headers: it strips any such headers sent by untrusted clients and only preserves those coming from trusted upstream proxies. By the time the ForwardAuth middleware processes the request, all X-Forwarded-* headers are guaranteed to be trustworthy, including those intentionally added by other middlewares in the chain — for example, the X-Forwarded-Prefix header set by the StripPrefix middleware.

If trustForwardHeader is not explicitly set, Traefik Hub API Gateway logs a warning at startup and uses a legacy behavior where some X-Forwarded-* headers (e.g. X-Forwarded-For, X-Forwarded-Proto) are removed but others (e.g. X-Forwarded-Prefix) are forwarded untouched. To silence this warning, explicitly set trustForwardHeader to true or false.

Set the trustForwardHeader option to true to trust all X-Forwarded-* headers.

headerField

You can define a header field to store the authenticated user using the headerField option.

Install Configuration

http:
  middlewares:
    test-auth:
      forwardAuth:
        # ...
        headerField: "X-WebAuth-User"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    # ...
    headerField: X-WebAuth-User

Forward-Request Headers

The following request properties are provided to the forward-auth target endpoint as X-Forwarded- headers.

Property	Forward-Request Header
HTTP Method	X-Forwarded-Method
Protocol	X-Forwarded-Proto
Host	X-Forwarded-Host
Request URI	X-Forwarded-Uri
Source IP-Address	X-Forwarded-For