ForwardAuth¶

Using an External Service to Forward Authentication

AuthForward

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 Examples¶

Docker & Swarm

# Forward authentication to example.com
labels:
  - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"

Kubernetes

# Forward authentication to example.com
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth

Consul Catalog

# Forward authentication to example.com
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"

File (YAML)

# Forward authentication to example.com
http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"

File (TOML)

# Forward authentication to example.com
[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"

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

Configuration Options¶

`address`¶

The address option defines the authentication server address.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"

Kubernetes

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

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"

`trustForwardHeader`¶

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

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    trustForwardHeader: true

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        trustForwardHeader: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    trustForwardHeader = true

`authResponseHeaders`¶

The authResponseHeaders option is the list of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    authResponseHeaders:
      - X-Auth-User
      - X-Secret

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        authResponseHeaders:
          - "X-Auth-User"
          - "X-Secret"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    authResponseHeaders = ["X-Auth-User", "X-Secret"]

`authResponseHeadersRegex`¶

The authResponseHeadersRegex option is the regex to match headers to copy from the authentication server response and set on forwarded request, after stripping all headers that match the regex. 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.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.authResponseHeadersRegex=^X-"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    authResponseHeadersRegex: ^X-

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeadersRegex=^X-"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        authResponseHeadersRegex: "^X-"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    authResponseHeadersRegex = "^X-"

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.

`authRequestHeaders`¶

The authRequestHeaders option is the 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.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.authRequestHeaders=Accept,X-CustomHeader"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    authRequestHeaders:
      - "Accept"
      - "X-CustomHeader"

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.authRequestHeaders=Accept,X-CustomHeader"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        authRequestHeaders:
          - "Accept"
          - "X-CustomHeader"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    authRequestHeaders = "Accept,X-CustomHeader"

`addAuthCookiesToResponse`¶

The addAuthCookiesToResponse option is the list of cookies to copy from the authentication server to the response, replacing any existing conflicting cookie from the forwarded response.

Info

Please note that all backend cookies matching the configured list will not be added to the response.

Docker

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.addAuthCookiesToResponse=Session-Cookie,State-Cookie"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    addAuthCookiesToResponse:
      - Session-Cookie
      - State-Cookie

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.addAuthCookiesToResponse=Session-Cookie,State-Cookie"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        addAuthCookiesToResponse:
          - "Session-Cookie"
          - "State-Cookie"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    addAuthCookiesToResponse = ["Session-Cookie", "State-Cookie"]

`forwardBody`¶

Optional, Default=false

Set the forwardBody option to true to send Body.

Info

As body is read inside Traefik before forwarding, this breaks streaming.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.forwardBody=true"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    forwardBody: true

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.forwardBody=true"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        forwardBody: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    forwardBody = true

`maxBodySize`¶

Optional, Default=-1

Set the maxBodySize to limit the body size in bytes. If body is bigger than this, it returns a 401 (unauthorized). Default is -1, which means no limit.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.maxBodySize=1000"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://example.com/auth
    forwardBody: true
    maxBodySize: 1000

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.maxBodySize=1000"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        maxBodySize: 1000

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    forwardBody = true
    maxBodySize = 1000

`tls`¶

Optional

Defines the TLS configuration used for the secure connection to the authentication server.

`ca`¶

Optional

ca is the path to the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"

Kubernetes

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

---
apiVersion: v1
kind: Secret
metadata:
  name: mycasercret
  namespace: default

data:
  # Must contain a certificate under either a `tls.ca` or a `ca.crt` key. 
  tls.ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        tls:
          ca: "path/to/local.crt"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    [http.middlewares.test-auth.forwardAuth.tls]
      ca = "path/to/local.crt"

`cert`¶

Optional

cert is the path to the public certificate used for the secure connection to the authentication server. When using this option, setting the key option is required.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
  - "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"

Kubernetes

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

---
apiVersion: v1
kind: Secret
metadata:
  name: mytlscert
  namespace: default

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        tls:
          cert: "path/to/foo.cert"
          key: "path/to/foo.key"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    [http.middlewares.test-auth.forwardAuth.tls]
      cert = "path/to/foo.cert"
      key = "path/to/foo.key"

Info

For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the secret field instead.

`key`¶

Optional

key is the path to the private key used for the secure connection to the authentication server. When using this option, setting the cert option is required.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
  - "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"

Kubernetes

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

---
apiVersion: v1
kind: Secret
metadata:
  name: mytlscert
  namespace: default

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        tls:
          cert: "path/to/foo.cert"
          key: "path/to/foo.key"

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    [http.middlewares.test-auth.forwardAuth.tls]
      cert = "path/to/foo.cert"
      key = "path/to/foo.key"

Info

For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the secret field instead.

`insecureSkipVerify`¶

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to the authentication server accepts any certificate presented by the server regardless of the hostnames it covers.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify=true"

Kubernetes

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

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://example.com/auth"
        tls:
          insecureSkipVerify: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-auth.forwardAuth]
    address = "https://example.com/auth"
    [http.middlewares.test-auth.forwardAuth.tls]
      insecureSkipVerify: true

`headerField`¶

Optional

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

Docker & Swarm

labels:
  - "traefik.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

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.headerField=X-WebAuth-User"

File (YAML)

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

File (TOML)

[http.middlewares.test-auth.forwardAuth]
  # ...
  headerField = "X-WebAuth-User"

`preserveLocationHeader`¶

Optional, Default=false

preserveLocationHeader defines whether to forward the Location header to the client as is or prefix it with the domain name of the authentication server.

Docker & Swarm

labels:
  - "traefik.http.middlewares.test-auth.forwardauth.preserveLocationHeader=true"

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    # ...
    preserveLocationHeader: true

Consul Catalog

- "traefik.http.middlewares.test-auth.forwardauth.preserveLocationHeader=true"

File (YAML)

http:
  middlewares:
    test-auth:
      forwardAuth:
        # ...
        preserveLocationHeader: true

File (TOML)

[http.middlewares.test-auth.forwardAuth]
  # ...
  preserveLocationHeader = true

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.

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.

ForwardAuth¶

Configuration Examples¶

Forward-Request Headers¶

Configuration Options¶

address¶

trustForwardHeader¶

authResponseHeaders¶

authResponseHeadersRegex¶

authRequestHeaders¶

addAuthCookiesToResponse¶

forwardBody¶

maxBodySize¶

tls¶

ca¶

cert¶

key¶

insecureSkipVerify¶

headerField¶

preserveLocationHeader¶

`address`¶

`trustForwardHeader`¶

`authResponseHeaders`¶

`authResponseHeadersRegex`¶

`authRequestHeaders`¶

`addAuthCookiesToResponse`¶

`forwardBody`¶

`maxBodySize`¶

`tls`¶

`ca`¶

`cert`¶

`key`¶

`insecureSkipVerify`¶

`headerField`¶

`preserveLocationHeader`¶