traefik/docs/content/middlewares/forwardauth.md

ForwardAuth

Using an External Service to Check for Credentials {: .subtitle }

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

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

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

"labels": {
  "traefik.http.middlewares.test-auth.forwardauth.address": "https://authserver.com/auth"
}

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

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

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

Configuration Options

address

The address option defines the authentication server address.

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

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://authserver.com/auth 

"labels": {
  "traefik.http.middlewares.test-auth.forwardauth.address": "https://authserver.com/auth"
}

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

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

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

trustForwardHeader

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

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

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

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

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

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

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

authResponseHeaders

The authResponseHeaders option is the list of the headers to copy from the authentication server to the request.

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

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

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

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

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

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

tls

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

tls.ca

TODO add description.

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

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

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

data:
  ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

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

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

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

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

tls.caOptional

TODO add description.

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

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://authserver.com/auth
    tls:
      caOptional: true

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

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

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

http:
  middlewares:
    test-auth:
      forwardAuth:
        address: "https://authserver.com/auth"
        tls:
          caOptional: true

tls.cert

TODO add description.

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"

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

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

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

"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"
}

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"

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

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

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

tls.key

TODO add description.

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"

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

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

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

"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"
}

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"

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

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

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

tls.insecureSkipVerify

TODO add description.

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

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  forwardAuth:
    address: https://authserver.com/auth
    insecureSkipVerify: true

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

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

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

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