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.	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
headerField	Defines a header field to store the authenticated user. More information here.		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.

headerField

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

Static 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