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

  1. # Forward authentication to example.com
  2. labels:
  3. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  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
  1. # Forward authentication to example.com
  2. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.address": "https://example.com/auth"
  3. }
  1. # Forward authentication to example.com
  2. labels:
  3. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  1. # Forward authentication to example.com
  2. [http.middlewares]
  3. [http.middlewares.test-auth.forwardAuth]
  4. address = "https://example.com/auth"
  1. # Forward authentication to example.com
  2. http:
  3. middlewares:
  4. test-auth:
  5. forwardAuth:
  6. address: "https://example.com/auth"

Configuration Options

address

The address option defines the authentication server address.

  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  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
  1. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.address": "https://example.com/auth"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
  1. [http.middlewares]
  2. [http.middlewares.test-auth.forwardAuth]
  3. address = "https://example.com/auth"
  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.

  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
  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
  1. - "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader": "true"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
  1. [http.middlewares]
  2. [http.middlewares.test-auth.forwardAuth]
  3. address = "https://example.com/auth"
  4. trustForwardHeader = true
  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.

  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
  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
  1. - "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders": "X-Auth-User,X-Secret"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
  1. [http.middlewares]
  2. [http.middlewares.test-auth.forwardAuth]
  3. address = "https://example.com/auth"
  4. authResponseHeaders = ["X-Auth-User", "X-Secret"]
  1. http:
  2. middlewares:
  3. test-auth:
  4. forwardAuth:
  5. address: "https://example.com/auth"
  6. authResponseHeaders:
  7. - "X-Auth-User"
  8. - "X-Secret"

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.

  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
  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. ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  1. - "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.tls.ca": "path/to/local.crt"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
  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"
  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
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
  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
  1. - "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional": "true"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
  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
  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.

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

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

  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify=true"
  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
  1. - "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"
  1. "labels": {
  2. "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify": "true"
  3. }
  1. labels:
  2. - "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"
  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
  1. http:
  2. middlewares:
  3. test-auth:
  4. forwardAuth:
  5. address: "https://example.com/auth"
  6. tls:
  7. insecureSkipVerify: true