cloudflare · RebeccaTamachiro · Jul 21, 2025 · Jun 30, 2025 · Jul 1, 2025 · Jul 1, 2025
@@ -23,7 +23,10 @@ Before you can protect your API or web application with mTLS rules, you need to:
 
 <Render file="mtls-api-shield-support" />
 
-<Render file="cloudflare-managed-client-cert" product="ssl" />
+:::caution
+
+By default, API Shield mTLS uses client certificates issued by a Cloudflare-managed CA. If you need to use certificates issued by another CA, you can use the API to [bring your own CA for mTLS](/ssl/client-certificates/byo-ca/).
+:::
 
 ## Create an mTLS rule via the Cloudflare dashboard
 

@@ -6,11 +6,11 @@ sidebar:
 
 ---
 
-import { GlossaryTooltip, Render } from "~/components"
+import { GlossaryDefinition, Render } from "~/components";
 
 <Render file="mtls-api-shield-support" />
 
-<GlossaryTooltip term="mTLS (mutual TLS)">Mutual TLS (mTLS)</GlossaryTooltip> authentication uses client certificates to ensure traffic between client and server is bidirectionally secure and trusted. mTLS also allows requests that do not authenticate via an identity provider — such as Internet-of-things (IoT) devices — to demonstrate they can reach a given resource.
+<GlossaryDefinition term="mTLS (mutual TLS)" />
 
 ![mTLS sequence diagram](~/assets/images/api-shield/api-shield-call-sequence.png)
 

@@ -6,7 +6,9 @@ sidebar:
   order: 1
 ---
 
-Mutual TLS [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) authentication uses client certificates to ensure traffic between client and server is bidirectionally secure and trusted. mTLS also allows requests that do not authenticate via an identity provider — such as Internet-of-things (IoT) devices — to demonstrate they can reach a given resource.
+import { GlossaryDefinition } from "~/components";
+
+<GlossaryDefinition term="mTLS (mutual TLS)" />
 
 [TLS (Transport Layer Security)](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) is a widely-used protocol to ensure secure communication over a network. It ensures confidentiality and integrity by encrypting data and validating the server using digital certificates.
 

@@ -20,5 +20,5 @@ There are two main ways to use mTLS at Cloudflare, either by using the Applicati
 | Mainly used for                                                       | External Authentication (that is, APIs)                                                                                                                                                                                                                                               | Internal Authentication (that is, employees)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Availability                                                          | By default, 100 Client Certificates per Zone are included for free. For more certificates or [API Shield features](/api-shield/), contact your account team.                                                                                                                          | Zero Trust Enterprise only feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | [Certificate Authority (CA)](/ssl/concepts/#certificate-authority-ca) | Cloudflare-managed or customer-uploaded (BYO CA). There's a soft-limit of up to [five customer-uploaded CAs](/ssl/client-certificates/byo-ca/#availability).                                                                                                                          | Customer-uploaded only (BYO CA). There's a soft-limit of up to [50 CAs](/cloudflare-one/account-limits/#access).                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Client Certificate Details | Forwarded to the origin server via [Cloudflare API](/ssl/client-certificates/enable-mtls/#cloudflare-api), [Cloudflare Workers](/ssl/client-certificates/enable-mtls/#cloudflare-workers), and [Managed Transforms](/ssl/client-certificates/enable-mtls/#managed-transforms). | Forwarded to the origin server via [Cloudflare API](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-api), [Cloudflare Workers](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-workers), and [Managed Transforms](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#managed-transforms). Client Certificate headers and [Cf-Access-Jwt-Assertion](/cloudflare-one/identity/authorization-cookie/validating-json/) JWT header can be forwarded to the origin server. |
+| Client Certificate Details | Forwarded to the origin server via [Cloudflare API](/ssl/client-certificates/forward-a-client-certificate/#cloudflare-api), [Cloudflare Workers](/ssl/client-certificates/forward-a-client-certificate/#cloudflare-workers), and [Managed Transforms](/ssl/client-certificates/forward-a-client-certificate/#managed-transforms). | Forwarded to the origin server via [Cloudflare API](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-api), [Cloudflare Workers](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-workers), and [Managed Transforms](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#managed-transforms). Client Certificate headers and [Cf-Access-Jwt-Assertion](/cloudflare-one/identity/authorization-cookie/validating-json/) JWT header can be forwarded to the origin server. |
 | Client Certificates Revocation                                        | Use the WAF [Custom Rules](/waf/custom-rules/) to check for [_cf.tls_client_auth.cert_revoked_](/ssl/client-certificates/revoke-client-certificate/), which only applies to Cloudflare-managed CA. <br /><br /> For BYO CAs, it would be the same approach as with Cloudflare Access. | Generate a [Certificate Revocation List (CRL)](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#create-a-crl) and enforce the revocation in a Cloudflare Worker.                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -10,7 +10,7 @@ This implementation requires an active [Zone](/fundamentals/concepts/accounts-an
 
 API Shield is not required to use mTLS. <br />
 
-By default, mTLS uses Client Certificates issued by a Cloudflare Managed CA. Cloudflare generates a unique CA for each customer account, meaning that Client Certificates all validate against an account-level Cloudflare CA.
+By default, mTLS uses Client Certificates issued by a Cloudflare Managed CA and set at account-level. If you have an Enterprise account, you also have the option to [bring your own CA](/ssl/client-certificates/byo-ca/).
 :::
 
 ## 1. Enable mTLS

@@ -33,7 +33,7 @@ Generally, ensure client certificates are rotated regularly and safely to reduce
 
 ## Forward a client certificate
 
-There are multiple ways to [forward a client certificate](/ssl/client-certificates/enable-mtls/#forward-a-client-certificate) to your origin server.
+There are multiple ways to [forward a client certificate](/ssl/client-certificates/forward-a-client-certificate/) to your origin server.
 
 ## Bring your own CA for mTLS
 
@@ -132,7 +132,7 @@ This expression will check for a specific [Client Certificate serial number](/ru
 
 ## Rate Limiting by Client Certificates
 
-By enabling [forwarding a certificate](/ssl/client-certificates/enable-mtls/#cloudflare-api) via the Cloudflare API, the first request of an mTLS connection will include the following headers:
+By enabling [forwarding a certificate](/ssl/client-certificates/forward-a-client-certificate/#cloudflare-api) via the Cloudflare API, every request of an mTLS connection will include the following headers:
 
 - `Cf-Client-Cert-Der-Base64` (raw certificate in DER format, encoded as base64)
 - `Cf-Client-Cert-Sha256` (SHA256 fingerprint of the certificate)

@@ -12,7 +12,7 @@ This requires an active Enterprise [Account](/fundamentals/concepts/accounts-and
 Setting up [mTLS](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) with [Cloudflare Access](/cloudflare-one/policies/access/) can help in cases where the customer:
 
 - Already has existing Client Certificates on devices.
-- Needs to protect Access applications with Bring Your Own CA (BYOCA).
+- Needs to protect Access applications with [Bring Your Own CA (BYOCA)](/ssl/client-certificates/byo-ca/).
 - Needs to integrate with a Zero Trust solution.
 
 ## 1. Create a CA

@@ -17,7 +17,7 @@ Cloudflare Workers runs after the Cloudflare WAF and Cloudflare Access. Review t
 
 All Client Certificate details can be found in the [tlsClientAuth](/workers/runtime-apis/request#incomingrequestcfproperties) object in Cloudflare Workers.
 
-Example Cloudflare Workers code to return all headers and gain visibility, including [Client Certificate headers](/ssl/client-certificates/enable-mtls/#cloudflare-workers):
+Example Cloudflare Workers code to return all headers and gain visibility, including [Client Certificate headers](/ssl/client-certificates/forward-a-client-certificate/#cloudflare-workers):
 
 <Tabs> <TabItem label="Module Worker" icon="seti:javascript">
 ```js

@@ -10,11 +10,11 @@ description: Cloudflare mTLS now supports client certificates that have not been
 
 ---
 
-import { Render, APIRequest } from "~/components"
+import { Render, APIRequest, Tabs, TabItem } from "~/components"
 
-This page explains how you can manage mTLS using client certificates that have not been issued by Cloudflare CA.
+This page explains how you can manage client certificates that have not been issued by Cloudflare CA. For a broader overview, refer to the [mTLS at Cloudflare learning path](/learning-paths/mtls/concepts/).
 
-This is especially useful if you already have mTLS implemented and client certificates are already installed on devices.
+Bring your own CA (BYOCA) is especially useful if you already have mTLS implemented and [client certificates are already installed](/ssl/client-certificates/#how-it-works) on devices.
 
 ## Availability
 
@@ -78,6 +78,42 @@ This is especially useful if you already have mTLS implemented and client certif
   "action": "block"
 ```
 
+### Multiple CAs for one hostname
+
+There can be multiple CAs (Cloudflare-managed or BYOCA) associated with the same hostname. For BYOCA certificates, the most recently deployed certificate will be prioritized.
+
+If you wish to remove the association from the Cloudflare-managed certificate and only use your BYOCA certificate(s):
+
+<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and domain.
+2. Go to **SSL/TLS** > **Client Certificates**.
+3. On the **Hosts** section of the **Client Certificates** card, select **Edit**.
+4. Select the cross next to the hostname you want to remove. The list of hostname associations will be updated.
+5. Select **Save** to confirm.
+
+</TabItem> <TabItem label="API">
+
+1. [List the hostname associations](/api/resources/certificate_authorities/subresources/hostname_associations/methods/get/) **without** the `mtls_certificate_id` parameter.
+
+<APIRequest
+  path="/zones/{zone_id}/certificate_authorities/hostname_associations"
+  method="GET"
+/>
+
+2. Copy the `hostnames` array returned by the API and update it, removing the hostname that should no longer use the Cloudflare-managed CA.
+3. Use the [Replace Hostname Associations endpoint](/api/resources/certificate_authorities/subresources/hostname_associations/methods/update/) **without** the `mtls_certificate_id` parameter to perform the action against the Cloudflare-managed CA. For `hostnames` use the list from the previous step.
+
+<APIRequest
+  path="/zones/{zone_id}/certificate_authorities/hostname_associations"
+  method="PUT"
+	json={{
+		"hostnames": ["<UPDATED_HOSTNAME_ASSOCIATIONS>"]
+	}}
+/>
+
+</TabItem> </Tabs>
+
 ## Delete an uploaded CA
 
 If you want to remove a CA that you have previously uploaded, you must first remove any hostname associations that it has.

@@ -2,7 +2,7 @@
 pcx_content_type: tutorial
 title: Configure your mobile app or IoT device
 sidebar:
-  order: 4
+  order: 9
 ---
 
 This tutorial demonstrates how to configure your Internet-of-things (IoT) device and mobile application to use client certificates with [API Shield](/api-shield/).

@@ -6,32 +6,37 @@ sidebar:
 
 ---
 
-To create a client certificate in the Cloudflare dashboard:
+import { Details } from "~/components";
 
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and application.
-2. Go to **SSL** > **Client Certificates**.
-3. Select **Create Certificate**.
+To create a client certificate on the Cloudflare dashboard:
 
-    :::caution
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and zone/domain.
+2. Go to **SSL/TLS** > **Client Certificates**.
+3. Select **Create Certificate** and fill in the required fields. You can choose one of the following options:
 
-    By default, client certificates are issued by a Cloudflare Managed CA. Cloudflare generates a unique CA for each account.
+  - Generate a private key and Certificate Signing Request (CSR) with Cloudflare.
+  - Use your own private key and CSR. This option allows you to also [label client certificates](/ssl/client-certificates/label-client-certificate/).
 
-    If you need to use certificates issued by another CA, use the API to [bring your own CA for mTLS](/ssl/client-certificates/byo-ca/).
-    :::
+    <Details header="Example OpenSSL command">
 
-4. For **Private key type**, select a value.
+    To generate and use your own CSR, you can run a command like the following:
 
-5. For **Certificate Validity**, select a value. The default value is 10 years.
+    ```sh
+    openssl req -new -newkey rsa:2048 -nodes -keyout client1.key -out client1.csr -subj '/C=GB/ST=London/L=London/O=Organization/CN=CommonName'
+    ```
 
-6. Select **Create**.
+    </Details>
 
-7. To copy the certificate or private key to your clipboard, use the **click to copy** link.
+:::note
+Client certificates created on the dashboard are issued by a [Cloudflare-managed CA](/ssl/client-certificates/#how-it-works). If you need to use certificates issued by another CA, use the API to [bring your own CA](/ssl/client-certificates/byo-ca/) instead.
+:::
 
-8. To close the dialog, select **OK**.
+4. Select a value for **Certificate Validity**, and choose **Create**.
+5. Make sure to copy the certificate and private key as they will no longer be displayed after creation.
+6. Select **OK** to confirm.
 
 ## Next steps
 
-You can now use the client certificate for multiple things, including:
+After creating the client certificate, make sure it is installed on the client devices and [enable mTLS](/ssl/client-certificates/enable-mtls/) for each hostname that should require a certificate from clients.
 
-* Adding an mTLS certificate binding to your [Worker](/workers/runtime-apis/bindings/mtls/).
-* Embedding a certificate in your [mobile app or IoT device](/ssl/client-certificates/configure-your-mobile-app-or-iot-device/).
+Refer to our [mTLS at Cloudflare learning path](/learning-paths/mtls/concepts/) for further context.
@@ -10,18 +10,28 @@ import { Render } from "~/components"
 
 You can enable mutual Transport Layer Security (mTLS) for any hostname.
 
-## Enable mTLS
+To enable mTLS for a host from the Cloudflare dashboard:
 
-To enable mutual Transport Layer Security (mTLS) for a host from the Cloudflare dashboard:
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and domain.
+2. Go to **SSL/TLS** > **Client Certificates**.
+3. On the **Hosts** section of the **Client Certificates** card, select **Edit**.
+4. Enter the name of a host in your current domain.
+:::note
+The domain (`example.com`) is automatically appended for you. This means that, if you want to enable mTLS for `abc.example.com`, you only need to type `abc`.
+:::
+5. Select **Save** to confirm.
 
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) 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**.
+## CAs in use
 
-After enabling mTLS for your host, you can enforce mTLS with [API Shield](/api-shield/security/mtls/configure/). While API Shield is **not required** to use mTLS, many teams may use mTLS to protect their APIs.
+As explained in the [Client certificates overview](/ssl/client-certificates/#how-it-works), Cloudflare validates client certificates against CAs set at account level. This means that these certificates can be used for validation across multiple zones/domains (`example.com`), as long as the zones are under the same Cloudflare account and you have enabled mTLS for the host.
 
-<Render file="cloudflare-managed-client-cert" />
+:::note[Bring your own CA]
+If you need to use your own CA (instead of the Cloudflare Managed CA), refer to [BYOCA](/ssl/client-certificates/byo-ca/). This is an API-only option, available on Enterprise accounts. In this case, certificates and hostname associations are **not** listed on your dashboard.
+:::
 
-<Render file="forward-client-certificate" />
+## Next steps
+
+After enabling mTLS for your host, you can:
+
+- Enforce mTLS with a WAF custom rule. Select **Create mTLS Rule** on the dashboard to use a template, or refer to our [mTLS at Cloudflare learning path](/learning-paths/mtls/mtls-app-security/#3-validate-the-client-certificate-in-the-waf) for further guidance.
+- Enforce mTLS with [API Shield](/api-shield/security/mtls/configure/). While API Shield is **not required** to use mTLS, many teams may use mTLS to protect their APIs.
@@ -0,0 +1,13 @@
+---
+pcx_content_type: how-to
+title: Forward certificate to server
+sidebar:
+  order: 6
+
+---
+
+Customers using [Cloudflare Access](/cloudflare-one/policies/access/) also have the option to forward client certificates to their origin server.
+
+import { Render } from "~/components";
+
+<Render file="forward-client-certificate" />