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.

    Docker

    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 (YAML)

    1. # Forward authentication to example.com
    2. http:
    3. middlewares:
    4. test-auth:
    5. forwardAuth:
    6. 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"

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

    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 (YAML)

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

    File (TOML)

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

    trustForwardHeader

    Set the trustForwardHeader option to true to trust all 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 (YAML)

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

    File (TOML)

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

    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

    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

    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"

    File (TOML)

    1. [http.middlewares]
    2. [http.middlewares.test-auth.forwardAuth]
    3. 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.

    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 (YAML)

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

    File (TOML)

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

    Tip

    Regular expressions and replacements can be tested using online tools such as Go Playground or the .

    When defining a regular expression within YAML, any escaped character needs to be escaped twice: example\.com needs to be written as example\\.com.

    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

    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 (YAML)

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

    File (TOML)

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

    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

    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
    10. ---
    11. apiVersion: v1
    12. kind: Secret
    13. metadata:
    14. name: mycasercret
    15. namespace: default
    16. data:
    17. # Must contain a certificate under either a `tls.ca` or a `ca.crt` key.
    18. tls.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 (YAML)

    1. http:
    2. middlewares:
    3. test-auth:
    4. forwardAuth:
    5. address: "https://example.com/auth"
    6. tls:
    7. 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"

    caOptional

    Optional

    The value of caOptional defines which policy should be used for the secure connection with TLS Client Authentication to the authentication server.

    If ca is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified.

    When this option is set to true, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid.

    When this option is set to false, a client certificate is requested during the handshake, and at least one valid certificate should be sent by the client.

    Docker

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

    Kubernetes

    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 (YAML)

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

    File (TOML)

    1. [http.middlewares]
    2. [http.middlewares.test-auth.forwardAuth]
    3. caOptional = true

    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

    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
    10. ---
    11. apiVersion: v1
    12. kind: Secret
    13. metadata:
    14. name: mytlscert
    15. namespace: default
    16. data:
    17. tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
    18. 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 (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"

    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"

    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

    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
    10. ---
    11. apiVersion: v1
    12. kind: Secret
    13. metadata:
    14. name: mytlscert
    15. namespace: default
    16. data:
    17. tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
    18. 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 (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"

    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"

    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

    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 (YAML)

    File (TOML)

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