ForwardAuth

Using an External Service to Check for Credentials

AuthForward

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

Configuration Examples

Docker

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

Kubernetes

  1. # Forward authentication to example.com
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: Middleware
  4. metadata:
  5.   name: test-auth
  6. spec:
  7.   forwardAuth:
  8.     address: https://example.com/auth

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.address": "https://example.com/auth"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. # Forward authentication to example.com
  2. http:
  3.   middlewares:
  4.     test-auth:
  5.       forwardAuth:
  6.         address: "https://example.com/auth"

Forward-Request Headers

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

PropertyForward-Request Header
HTTP MethodX-Forwarded-Method
ProtocolX-Forwarded-Proto
HostX-Forwarded-Host
Request URIX-Forwarded-Uri
Source IP-AddressX-Forwarded-For

Configuration Options

address

The address option defines the authentication server address.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.address": "https://example.com/auth"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"

trustForwardHeader

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

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     trustForwardHeader: true

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader": "true"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         trustForwardHeader: true

authResponseHeaders

The authResponseHeaders option is the list of the headers to copy from the authentication server to the request. All incoming request’s headers in this list are deleted from the request before any copy happens.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     authResponseHeaders:
  9.       - X-Auth-User
  10.       - X-Secret

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders": "X-Auth-User,X-Secret"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         authResponseHeaders:
  7.           - "X-Auth-User"
  8.           - "X-Secret"

authResponseHeadersRegex

The authResponseHeadersRegex option is the regex to match the headers that should be copied from the authentication server to the request. All incoming request’s headers matching this regex are deleted from the request before any copy happens. It allows partial matching of the regular expression against the header’s key. You should use start of string (^) and end of string ($) anchors to ensure a full match against the header’s key.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     authResponseHeadersRegex: ^X-

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.authResponseHeadersRegex": "^X-"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         authResponseHeadersRegex: "^X-"

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 will be passed.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     authRequestHeaders:
  9.       - "Accept"
  10.       - "X-CustomHeader"

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.authRequestHeaders": "Accept,X-CustomHeader"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         authRequestHeaders:
  7.           - "Accept"
  8.           - "X-CustomHeader"

tls

The tls option is the TLS configuration from Traefik to the authentication server.

tls.ca

Certificate Authority used for the secured connection to the authentication server.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     tls:
  9.       caSecret: mycasercret
  11. ---
  12. apiVersion: v1
  13. kind: Secret
  14. metadata:
  15.   name: mycasercret
  16.   namespace: default
  18. data:
  19.   ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.tls.ca": "path/to/local.crt"
  3. }

Rancher

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

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         tls:
  7.           ca: "path/to/local.crt"

tls.caOptional

Policy used for the secured connection with TLS Client Authentication to the authentication server. Requires tls.ca to be defined.

  • true: VerifyClientCertIfGiven
  • false: RequireAndVerifyClientCert
  • if tls.ca is undefined NoClientCert

Docker

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     tls:
  9.       caOptional: true

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional": "true"
  3. }

Rancher

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.forwardAuth]
  3.     address = "https://example.com/auth"
  4.     [http.middlewares.test-auth.forwardAuth.tls]
  5.       caOptional = true

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         tls:
  7.           caOptional: true

tls.cert

Public certificate used for the secured connection to the authentication server.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     tls:
  9.       certSecret: mytlscert
  11. ---
  12. apiVersion: v1
  13. kind: Secret
  14. metadata:
  15.   name: mytlscert
  16.   namespace: default
  18. data:
  19.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  20.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.tls.cert": "path/to/foo.cert",
  3.   "traefik.http.middlewares.test-auth.forwardauth.tls.key": "path/to/foo.key"
  4. }

Rancher

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

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.forwardAuth]
  3.     address = "https://example.com/auth"
  4.     [http.middlewares.test-auth.forwardAuth.tls]
  5.       cert = "path/to/foo.cert"
  6.       key = "path/to/foo.key"

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         tls:
  7.           cert: "path/to/foo.cert"
  8.           key: "path/to/foo.key"

Info

For security reasons, the field doesn’t exist for Kubernetes IngressRoute, and one should use the secret field instead.

tls.key

Private certificate used for the secure connection to the authentication server.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     tls:
  9.       certSecret: mytlscert
  11. ---
  12. apiVersion: v1
  13. kind: Secret
  14. metadata:
  15.   name: mytlscert
  16.   namespace: default
  18. data:
  19.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  20.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.tls.cert": "path/to/foo.cert",
  3.   "traefik.http.middlewares.test-auth.forwardauth.tls.key": "path/to/foo.key"
  4. }

Rancher

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

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.forwardAuth]
  3.     address = "https://example.com/auth"
  4.     [http.middlewares.test-auth.forwardAuth.tls]
  5.       cert = "path/to/foo.cert"
  6.       key = "path/to/foo.key"

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         tls:
  7.           cert: "path/to/foo.cert"
  8.           key: "path/to/foo.key"

Info

For security reasons, the field doesn’t exist for Kubernetes IngressRoute, and one should use the secret field instead.

tls.insecureSkipVerify

If insecureSkipVerify is true, TLS for the connection to authentication server accepts any certificate presented by the server and any host name in that certificate.

Docker

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

Kubernetes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   forwardAuth:
  7.     address: https://example.com/auth
  8.     tls:
  9.       insecureSkipVerify: true

Consul Catalog

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

Marathon

  1. "labels": {
  2.   "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify": "true"
  3. }

Rancher

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"

File (TOML)

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

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       forwardAuth:
  5.         address: "https://example.com/auth"
  6.         tls:
  7.           insecureSkipVerify: true