Enable mTLS

You can enable mutual Transport Layer Security (mTLS) for any hostname.

Enable mTLS

To enable mutual Transport Layer Security (mTLS) for a host from the Cloudflare dashboard:

1. Log in to the Cloudflare dashboard ↗ and select your account and application.
2. Go to SSL > Client Certificates.
3. To enable mTLS for a host, select Edit in the Hosts section of the Client Certificates card.
4. Enter the name of a host in your current application and press Enter.
5. Select Save.

After enabling mTLS for your host, you can enforce mTLS with API Shield. While API Shield is not required to use mTLS, many teams may use mTLS to protect their APIs.

Warning

By default, API Shield mTLS uses client certificates issued by a Cloudflare Managed CA. Cloudflare generates a unique CA for each account.

If you need to use certificates issued by another CA, you can use the API to bring your own CA for mTLS.

Forward a client certificate

In addition to enforcing mTLS authentication for your host, you can also forward a client certificate to your origin server as an HTTP header. This setup is often helpful for server logging.

To avoid adding the certificate to every single request, the certificate is only forwarded on the first request of an mTLS connection.

Warning

This process is only available on accounts with Cloudflare Access.

Cloudflare API

The most common approach to forwarding a certificate is to use the Cloudflare API to update an mTLS certificate's hostname settings.

Required API token permissions

At least one of the following token permissions is required:

• Access: Mutual TLS Certificates Write

Update an mTLS certificate's hostname settings

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/access/certificates/settings" \
  --request PUT \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
  --json '{
    "settings": [
        {
            "hostname": "<HOSTNAME>",
            "china_network": false,
            "client_certificate_forwarding": true
        }
    ]
  }'

Once client_certificate_forwarding is set to true, the first request of an mTLS connection will now include the following headers:

• Cf-Client-Cert-Der-Base64
• Cf-Client-Cert-Sha256

Managed Transforms

You can also modify HTTP response headers using Managed Transforms to pass along TLS client auth headers.

Cloudflare Workers

Additionally, Workers can provide details around the client certificate.

const tlsHeaders = {
    'X-CERT-ISSUER-DN': request.cf.tlsClientAuth.certIssuerDN,
    'X-CERT-SUBJECT-DN': request.cf.tlsClientAuth.certSubjectDN,
    'X-CERT-ISSUER-DN-L': request.cf.tlsClientAuth.certIssuerDNLegacy,
    'X-CERT-SUBJECT-DN-L': request.cf.tlsClientAuth.certSubjectDNLegacy,
    'X-CERT-SERIAL': request.cf.tlsClientAuth.certSerial,
    'X-CERT-FINGER': request.cf.tlsClientAuth.certFingerprintSHA1,
    'X-CERT-VERIFY': request.cf.tlsClientAuth.certVerify,
    'X-CERT-NOTBE': request.cf.tlsClientAuth.certNotBefore,
    'X-CERT-NOTAF': request.cf.tlsClientAuth.certNotAfter
};