Skip to main content

Mutual TLS stage

authentik: 2025.6.0+PreviewEnterprise

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​

Add this configuration snippet in your authentik virtual host:

# 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 for reference.

nginx Ingress​

Add these annotations to your authentik ingress object:

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 for reference.

Traefik Standalone​

Add this snippet to your traefik configuration:

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 for reference.

Traefik Ingress​

Create a middleware object with these options:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-passtlsclientcert
spec:
    passTLSClientCert:
        pem: true

See the Traefik PassTLSClientCert documentation for reference.

Envoy​

See the Envoy mTLS documentation and Envoy header documentation for configuration.

No reverse proxy​

When using authentik without a reverse proxy, select the certificate authorities in the corresponding brand 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.