website/docs: add docs for MTLS Stage (#14571)
* website/docs: add docs for MTLS Stage Signed-off-by: Jens Langhammer <jens@goauthentik.io> * update Signed-off-by: Jens Langhammer <jens@goauthentik.io> * update docs Signed-off-by: Jens Langhammer <jens@goauthentik.io> * Apply suggestions from code review Co-authored-by: Dewi Roberts <dewi@goauthentik.io> Signed-off-by: Jens L. <jens@beryju.org> * Apply suggestions from code review Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Jens L. <jens@beryju.org> * Apply suggestions from code review Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Jens L. <jens@beryju.org> * update brand docs Signed-off-by: Jens Langhammer <jens@goauthentik.io> * remove code changes Signed-off-by: Jens Langhammer <jens@goauthentik.io> * fix build Signed-off-by: Jens Langhammer <jens@goauthentik.io> * reword Signed-off-by: Jens Langhammer <jens@goauthentik.io> * Update website/docs/add-secure-apps/flows-stages/stages/mtls/index.md Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> * Update website/docs/add-secure-apps/flows-stages/stages/mtls/index.md Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> --------- Signed-off-by: Jens Langhammer <jens@goauthentik.io> Signed-off-by: Jens L. <jens@beryju.org> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com> Co-authored-by: Dewi Roberts <dewi@goauthentik.io> Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
This commit is contained in:
Jens L.
@ -1,5 +1,6 @@
|
||||
---
|
||||
title: Flow Context
|
||||
toc_max_heading_level: 5
|
||||
---
|
||||
|
||||
Each flow execution has an independent _context_. This context holds all of the arbitrary data about that specific flow, data which can then be used and transformed by stages and policies.
|
||||
@ -156,6 +157,7 @@ Possible options:
|
||||
- `auth_mfa` (Authentication via MFA device without password)
|
||||
- `auth_webauthn_pwl` (Passwordless authentication via WebAuthn with Passkeys)
|
||||
- `jwt` ([M2M](../../../providers/oauth2/client_credentials.mdx) authentication via an existing JWT)
|
||||
- `mtls` (Authentication via Certificate, see [Mutual TLS Stage](../../stages/mtls/index.md))
|
||||
|
||||
##### `auth_method_args` (dictionary)
|
||||
|
||||
@ -176,7 +178,10 @@ Example:
|
||||
// JWT information when `auth_method` `jwt` was used
|
||||
"jwt": {},
|
||||
"source": null,
|
||||
"provider": null
|
||||
"provider": null,
|
||||
// Certificate used for authentication
|
||||
// applies for `auth_method` `mtls`
|
||||
"certificate": {}
|
||||
}
|
||||
```
|
||||
|
||||
@ -203,3 +208,22 @@ If _Show matched user_ is disabled, this key will be set to the user identifier
|
||||
[Set this key](../../../../customize/policies/expression/managing_flow_context_keys.md) in an Expression Policy to override [Redirect stage](../../stages/redirect/index.md) to force it to redirect to a certain URL or flow. This is useful when a flow requires that the redirection target be decided dynamically.
|
||||
|
||||
Use the format `ak-flow://{slug}` to use the Redirect stage in Flow mode. Any other format will result in the Redirect stage running in Static mode.
|
||||
|
||||
#### Mutual TLS Stage
|
||||
|
||||
##### `certificate` (dictionary):ak-version[2025.6]
|
||||
|
||||
This key is set by the Mutual TLS Stage during enrollment and contains data about the certificate supplied by the browser.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"serial_number": "1234",
|
||||
"subject": "CN=client",
|
||||
"issuer": "CN=authentik Test CA, O=authentik, OU=Self-signed",
|
||||
"fingerprint_sha256": "08:D4:A4:79:25:CA:C3:51:28:88:BB:30:C2:96:C3:44:5A:EB:18:07:84:CA:B4:75:27:74:61:19:8A:6A:AF:FC",
|
||||
"fingerprint_sha1": "5D:14:0D:5F:A2:7E:14:B0:F1:1D:6F:CD:E3:4B:81:68:71:24:1A:70",
|
||||
"raw": "-----BEGIN CERTIFICATE-----...."
|
||||
}
|
||||
```
|
||||
|
||||
124
website/docs/add-secure-apps/flows-stages/stages/mtls/index.md
Normal file
124
website/docs/add-secure-apps/flows-stages/stages/mtls/index.md
Normal file
@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Mutual TLS stage
|
||||
authentik_version: "2025.6"
|
||||
authentik_preview: true
|
||||
authentik_enterprise: true
|
||||
toc_max_heading_level: 5
|
||||
---
|
||||
|
||||
The Mutual TLS stage enables authentik to use client certificates to enroll and authenticate users. These certificates can be local to the device or available via PIV Smart Cards, Yubikeys, etc.
|
||||
|
||||
Management of client certificates is out of the scope of this document.
|
||||
|
||||
## Reverse-proxy configuration
|
||||
|
||||
Using the Mutual TLS stage requires special configuration of any reverse proxy that is used in front of authentik, because the reverse-proxy interacts directly with the browser.
|
||||
|
||||
- nginx
|
||||
- [Standalone nginx](#nginx-standalone)
|
||||
- [nginx kubernetes ingress](#nginx-ingress)
|
||||
- Traefik
|
||||
- [Standalone Traefik](#traefik-standalone)
|
||||
- [Traefik kubernetes ingress](#traefik-ingress)
|
||||
- [envoy](#envoy)
|
||||
- [No reverse proxy](#no-reverse-proxy)
|
||||
|
||||
#### nginx Standalone
|
||||
|
||||
Add this configuration snippet in your authentik virtual host:
|
||||
|
||||
```nginx
|
||||
# server {
|
||||
ssl_client_certificate /etc/ssl/path-to-my-ca.pem;
|
||||
ssl_verify_client on;
|
||||
|
||||
# location / {
|
||||
proxy_set_header ssl-client-cert $ssl_client_escaped_cert;
|
||||
# }
|
||||
# }
|
||||
```
|
||||
|
||||
See [nginx documentation](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) for reference.
|
||||
|
||||
#### nginx Ingress
|
||||
|
||||
Add these annotations to your authentik ingress object:
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
|
||||
# This secret needs to contain `ca.crt` which is the certificate authority to validate against.
|
||||
nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName
|
||||
```
|
||||
|
||||
See [ingress-nginx documentation](https://kubernetes.github.io/ingress-nginx/examples/auth/client-certs/) for reference.
|
||||
|
||||
#### Traefik Standalone
|
||||
|
||||
Add this snippet to your traefik configuration:
|
||||
|
||||
```yaml
|
||||
tls:
|
||||
options:
|
||||
default:
|
||||
clientAuth:
|
||||
# in PEM format. each file can contain multiple CAs.
|
||||
caFiles:
|
||||
- tests/clientca1.crt
|
||||
- tests/clientca2.crt
|
||||
clientAuthType: RequireAndVerifyClientCert
|
||||
```
|
||||
|
||||
See the [Traefik mTLS documentation](https://doc.traefik.io/traefik/https/tls/#client-authentication-mtls) for reference.
|
||||
|
||||
#### Traefik Ingress
|
||||
|
||||
Create a middleware object with these options:
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-passtlsclientcert
|
||||
spec:
|
||||
passTLSClientCert:
|
||||
pem: true
|
||||
```
|
||||
|
||||
See the [Traefik PassTLSClientCert documentation](https://doc.traefik.io/traefik/middlewares/http/passtlsclientcert/) for reference.
|
||||
|
||||
#### Envoy
|
||||
|
||||
See the [Envoy mTLS documentation](https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/securing#use-mutual-tls-mtls-to-enforce-client-certificate-authentication) and [Envoy header documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert) for configuration.
|
||||
|
||||
#### No reverse proxy
|
||||
|
||||
When using authentik without a reverse proxy, select the certificate authorities in the corresponding [brand](../../../../sys-mgmt/brands.md#client-certificates) for the domain, under **Other global settings**.
|
||||
|
||||
## Stage configuration
|
||||
|
||||
1. Log in as an admin to authentik, and go to the Admin interface.
|
||||
|
||||
2. In the Admin interface, navigate to **System -> Certificates**
|
||||
|
||||
3. Create a new certificate for the Certificate Authority used to sign client certificates.
|
||||
|
||||
4. In the Admin interface, navigate to **Flows -> Stages**.
|
||||
|
||||
5. Click **Create**, and select **Mutual TLS Stage**, and in the **New stage** box, define the following fields:
|
||||
|
||||
- **Name**: define a descriptive name, such as "chrome-device-trust".
|
||||
|
||||
- **Stage-specific settings**
|
||||
|
||||
- **Mode**: Configure the mode this stage operates in.
|
||||
|
||||
- **Certificate optional**: When no certificate is provided by the user or the reverse proxy, the flow will continue to the next stage.
|
||||
- **Certificate required**: When no certificate is provided, the flow ends with an error message.
|
||||
|
||||
- **Certificate authorities**: Select the certificate authorities used to sign client certificates.
|
||||
|
||||
- **Certificate attribute**: Select the attribute of the certificate to be used to find a user for authentication.
|
||||
|
||||
- **User attribute**: Select the attribute of the user the certificate should be compared against.
|
||||
|
||||
6. Click **Finish**.
|
||||
Reference in New Issue
Block a user