traefik/docs/content/middlewares/http/forwardauth.md

525 lines
13 KiB
Markdown
Raw Normal View History

---
title: "Traefik ForwardAuth Documentation"
description: "In Traefik Proxy, the HTTP ForwardAuth middleware delegates authentication to an external Service. Read the technical documentation."
---
# ForwardAuth
2021-02-11 13:34:04 +00:00
Using an External Service to Forward Authentication
{: .subtitle }
2021-06-11 13:30:05 +00:00
![AuthForward](../../assets/img/middleware/authforward.png)
2021-02-11 13:34:04 +00:00
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.
## Configuration Examples
2019-03-29 11:34:05 +00:00
```yaml tab="Docker"
2020-03-13 21:50:05 +00:00
# Forward authentication to example.com
2019-03-29 11:34:05 +00:00
labels:
2020-03-13 21:50:05 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
```
```yaml tab="Kubernetes"
2020-03-13 21:50:05 +00:00
# Forward authentication to example.com
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
2020-03-13 21:50:05 +00:00
# Forward authentication to example.com
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
2019-10-15 15:34:08 +00:00
```
```yaml tab="File (YAML)"
2020-03-13 21:50:05 +00:00
# Forward authentication to example.com
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
```
```toml tab="File (TOML)"
# Forward authentication to example.com
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
```
2020-11-10 16:50:04 +00:00
## 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`
The `address` option defines the authentication server address.
```yaml tab="Docker"
labels:
2020-03-13 21:50:05 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
2020-03-13 21:50:05 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
2019-10-15 15:34:08 +00:00
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
```
### `trustForwardHeader`
2021-02-11 13:34:04 +00:00
Set the `trustForwardHeader` option to `true` to trust all `X-Forwarded-*` headers.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
2019-03-29 11:34:05 +00:00
```
2019-04-03 12:32:04 +00:00
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
2019-04-03 12:32:04 +00:00
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
2019-04-03 12:32:04 +00:00
trustForwardHeader: true
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
trustForwardHeader: true
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
trustForwardHeader = true
```
### `authResponseHeaders`
2021-02-11 13:34:04 +00:00
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.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
2019-04-03 12:32:04 +00:00
authResponseHeaders:
2019-09-23 15:00:06 +00:00
- X-Auth-User
- X-Secret
2019-04-03 12:32:04 +00:00
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
authResponseHeaders:
2019-09-23 15:00:06 +00:00
- "X-Auth-User"
- "X-Secret"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
authResponseHeaders = ["X-Auth-User", "X-Secret"]
```
### `authResponseHeadersRegex`
2021-02-11 13:34:04 +00:00
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.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeadersRegex=^X-"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
authResponseHeadersRegex: ^X-
```
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeadersRegex=^X-"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
address: "https://example.com/auth"
authResponseHeadersRegex: "^X-"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
authResponseHeadersRegex = "^X-"
```
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
2020-10-07 14:36:04 +00:00
### `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.
2021-02-11 13:34:04 +00:00
If not set or empty then all request headers are passed.
2020-10-07 14:36:04 +00:00
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.authRequestHeaders=Accept,X-CustomHeader"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
2020-10-07 14:36:04 +00:00
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
authRequestHeaders:
- "Accept"
- "X-CustomHeader"
```
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.authRequestHeaders=Accept,X-CustomHeader"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
address: "https://example.com/auth"
authRequestHeaders:
- "Accept"
- "X-CustomHeader"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
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.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
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=
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
tls:
ca: "path/to/local.crt"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
[http.middlewares.test-auth.forwardAuth.tls]
ca = "path/to/local.crt"
```
#### `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.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
tls:
certSecret: mytlscert
---
apiVersion: v1
kind: Secret
metadata:
name: mytlscert
namespace: default
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
tls:
cert: "path/to/foo.cert"
key: "path/to/foo.key"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
[http.middlewares.test-auth.forwardAuth.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-09-23 12:32:04 +00:00
!!! info
2021-02-11 13:34:04 +00:00
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
2019-04-03 12:32:04 +00:00
#### `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.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
tls:
certSecret: mytlscert
---
apiVersion: v1
kind: Secret
metadata:
name: mytlscert
namespace: default
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
2019-07-22 07:58:04 +00:00
tls:
cert: "path/to/foo.cert"
key: "path/to/foo.key"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
[http.middlewares.test-auth.forwardAuth.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-09-23 12:32:04 +00:00
!!! info
2021-02-11 13:34:04 +00:00
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
#### `insecureSkipVerify`
_Optional, Default=false_
2021-02-11 13:34:04 +00:00
If `insecureSkipVerify` is `true`, the TLS connection to the authentication server accepts any certificate presented by the server regardless of the hostnames it covers.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify=true"
```
```yaml tab="Kubernetes"
2023-03-20 14:38:08 +00:00
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: https://example.com/auth
tls:
insecureSkipVerify: true
```
2019-10-15 15:34:08 +00:00
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
forwardAuth:
2020-03-13 21:50:05 +00:00
address: "https://example.com/auth"
tls:
insecureSkipVerify: true
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
[http.middlewares.test-auth.forwardAuth.tls]
insecureSkipVerify: true
```