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.
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
Field | Description |
---|---|
address | The address option defines the authentication server address. |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
trustForwardHeader
Field | Description |
---|---|
trustForwardHeader | Set the trustForwardHeader option to true to trust all X-Forwarded-* headers. |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
trustForwardHeader: true
authResponseHeaders
Field | Description |
---|---|
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. |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
authResponseHeaders:
- X-Auth-User
- X-Secret
authResponseHeadersRegex
Field | Description |
---|---|
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. |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
authResponseHeadersRegex: ^X-
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
Field | Description |
---|---|
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. |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
authRequestHeaders:
- "Accept"
- "X-CustomHeader"
addAuthCookiesToResponse
Field | Description |
---|---|
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. |
Please note that all backend cookies matching the configured list will not be added to the response.
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
addAuthCookiesToResponse:
- Session-Cookie
- State-Cookie
tls
Field | Description | Required |
---|---|---|
tls | Defines the TLS configuration used for the secure connection to the authentication server. | No |
ca
Field | Description | Required |
---|---|---|
ca | ca is the path to the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle. | No |
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=
cert
Field | Description | Required |
---|---|---|
cert | 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. | No |
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=
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the secret
field instead.
key
Field | Description | Required |
---|---|---|
key | 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. | No |
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=
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the secret
field instead.
insecureSkipVerify
Field | Description | Default | Required |
---|---|---|---|
insecureSkipVerify | If insecureSkipVerify is true , the TLS connection to the authentication server accepts any certificate presented by the server regardless of the hostnames it covers. | false | No |
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
tls:
insecureSkipVerify: true
Example
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth