From 07c5d3866ed68e20d1874c84007855c1ca5d2054 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 30 Jun 2025 19:10:11 +0100 Subject: [PATCH 01/33] Add (mTLS) to page title --- src/content/docs/ssl/client-certificates/index.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 93140c2f0c94cf..e4fb36f6a6f383 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -1,11 +1,10 @@ --- pcx_content_type: concept -title: Client certificates +title: Client certificates (mTLS) sidebar: order: 6 head: [] -description: Use Cloudflare public key infrastructure (PKI) to create client - certificates and enforce mutual Transport Layer Security (mTLS) encryption. +description: Use Cloudflare public key infrastructure (PKI) to create client certificates and enforce mutual Transport Layer Security (mTLS) encryption. --- From 7bae016674adefaaa7e60226c5c01b93c846a0fa Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 16:00:48 +0100 Subject: [PATCH 02/33] Review glossary entry and apply mTLS definition throughout --- src/content/docs/api-shield/security/mtls/index.mdx | 4 ++-- .../docs/learning-paths/mtls/concepts/index.mdx | 4 +++- src/content/docs/ssl/client-certificates/index.mdx | 10 ++++++++-- src/content/glossary/ssl.yaml | 2 +- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/src/content/docs/api-shield/security/mtls/index.mdx b/src/content/docs/api-shield/security/mtls/index.mdx index 2c89f5322f33bf..587d81d91c8d76 100644 --- a/src/content/docs/api-shield/security/mtls/index.mdx +++ b/src/content/docs/api-shield/security/mtls/index.mdx @@ -6,11 +6,11 @@ sidebar: --- -import { GlossaryTooltip, Render } from "~/components" +import { GlossaryDefinition, Render } from "~/components"; -Mutual TLS (mTLS) 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. + ![mTLS sequence diagram](~/assets/images/api-shield/api-shield-call-sequence.png) diff --git a/src/content/docs/learning-paths/mtls/concepts/index.mdx b/src/content/docs/learning-paths/mtls/concepts/index.mdx index a41bec30a1f882..7b2347ad2aed80 100644 --- a/src/content/docs/learning-paths/mtls/concepts/index.mdx +++ b/src/content/docs/learning-paths/mtls/concepts/index.mdx @@ -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"; + + [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. diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index e4fb36f6a6f383..f6167cbd073232 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -8,9 +8,15 @@ description: Use Cloudflare public key infrastructure (PKI) to create client cer --- -import { Render } from "~/components" +import { GlossaryDefinition, Render } from "~/components"; -Use Cloudflare public key infrastructure (PKI) to create client certificates. Use these certificates with Cloudflare [API Shield](/api-shield/) or [Cloudflare Workers](/workers/runtime-apis/bindings/mtls/) to enforce mutual Transport Layer Security (mTLS) encryption. +Use Cloudflare public key infrastructure (PKI) to create client certificates and enable mutual TLS authentication. + + + +--- + +Use these certificates with Cloudflare [API Shield](/api-shield/) or [Cloudflare Workers](/workers/runtime-apis/bindings/mtls/) to enforce mutual Transport Layer Security (mTLS) encryption. diff --git a/src/content/glossary/ssl.yaml b/src/content/glossary/ssl.yaml index 40d875d910a4a9..6e9735546f0ded 100644 --- a/src/content/glossary/ssl.yaml +++ b/src/content/glossary/ssl.yaml @@ -93,7 +93,7 @@ entries: - term: mTLS (mutual TLS) general_definition: |- - mTLS is a common security practice that uses TLS certificates to ensure that traffic between a client and server is secure and trusted in both directions. + [Mutual TLS (mTLS)](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) authentication is a common security practice that 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. associated_products: - API Shield - Cloudflare One From 8e9fe6b2b5ed45f769beabd08715c43970b63c21 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 17:05:52 +0100 Subject: [PATCH 03/33] Link to BYOCA and learning path from client certs landing page --- src/content/docs/ssl/client-certificates/index.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index f6167cbd073232..1f294274ced020 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -10,10 +10,13 @@ description: Use Cloudflare public key infrastructure (PKI) to create client cer import { GlossaryDefinition, Render } from "~/components"; -Use Cloudflare public key infrastructure (PKI) to create client certificates and enable mutual TLS authentication. +Use Cloudflare public key infrastructure (PKI) to create client certificates, or [bring your own CA for mTLS](/ssl/client-certificates/byo-ca/). +:::note[mTLS at Cloudflare] +For a broader overview of mTLS at Cloudflare refer to the [learning path](/learning-paths/mtls/concepts/). +::: --- Use these certificates with Cloudflare [API Shield](/api-shield/) or [Cloudflare Workers](/workers/runtime-apis/bindings/mtls/) to enforce mutual Transport Layer Security (mTLS) encryption. From a18bb39625fcb4ef17ee3f5a17df949a4c670042 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 17:20:49 +0100 Subject: [PATCH 04/33] Review content in byo-ca and adjust page intro --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index e7e92381de555d..b80ec81dac42c5 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -12,9 +12,9 @@ description: Cloudflare mTLS now supports client certificates that have not been import { Render, APIRequest } 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 of mTLS at Cloudflare refer to [learning paths](/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 on devices. ## Availability From a01ceed3709cb335d9ae9641d2932f560521580b Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 17:47:24 +0100 Subject: [PATCH 05/33] Remove step-like sections and add new proposed h2s --- .../docs/ssl/client-certificates/index.mdx | 27 +++---------------- 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 1f294274ced020..b1a53efdbd6bbc 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -15,31 +15,10 @@ Use Cloudflare public key infrastructure (PKI) to create client certificates, or :::note[mTLS at Cloudflare] -For a broader overview of mTLS at Cloudflare refer to the [learning path](/learning-paths/mtls/concepts/). +For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning-paths/mtls/concepts/). ::: ---- - -Use these certificates with Cloudflare [API Shield](/api-shield/) or [Cloudflare Workers](/workers/runtime-apis/bindings/mtls/) to enforce mutual Transport Layer Security (mTLS) encryption. - - - -## API Shield - -To use API Shield to protect your API or web application, you must do the following: - -1. Use Cloudflare’s fully hosted public key infrastructure (PKI) to [create a client certificate](/ssl/client-certificates/create-a-client-certificate/). - -2. [Configure your mobile app or IoT device](/ssl/client-certificates/configure-your-mobile-app-or-iot-device/) to use your Cloudflare-issued client certificate. - -3. [Enable mTLS](/ssl/client-certificates/enable-mtls/) for the hosts you wish to protect with API Shield. - -4. Create WAF custom rules that [require API requests to present a valid client certificate](/api-shield/security/mtls/configure/). - - -## Workers +## Scope -To authenticate Workers requests using mTLS: -1. Use Cloudflare’s fully hosted public key infrastructure (PKI) to [create a client certificate](/ssl/client-certificates/create-a-client-certificate/). -2. Create and use an [mTLS binding](/workers/runtime-apis/bindings/mtls/) to authenticate Workers connections. +## Use cases From 17d85fabbef2fb9c66adf9ba40e04e6565eb823d Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 18:11:02 +0100 Subject: [PATCH 06/33] Fill in Scope section and delete redundant partial --- src/content/docs/ssl/client-certificates/index.mdx | 9 ++++++++- src/content/partials/ssl/client-cert-shared.mdx | 13 ------------- 2 files changed, 8 insertions(+), 14 deletions(-) delete mode 100644 src/content/partials/ssl/client-cert-shared.mdx diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index b1a53efdbd6bbc..adedc3196eabe1 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -20,5 +20,12 @@ For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning ## Scope +Cloudflare validates client certificates with one CA, 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 account and mTLS has been enabled for the requested hosts (`host.example.com`). -## Use cases +If you use the Cloudflare-managed CA, client certificates that you create can be used with hosts in any zone/domain that belongs to your Cloudflare account. If you [bring your own CA](/ssl/client-certificates/byo-ca/), it will be set at account level and you can associate it with hosts in different zones/domains. + +:::note +Bring your own CA (BYOCA) is API-only and certificates or host associations will **not** show up on your dashboard. +::: + +## Use cases \ No newline at end of file diff --git a/src/content/partials/ssl/client-cert-shared.mdx b/src/content/partials/ssl/client-cert-shared.mdx deleted file mode 100644 index 55fc237da227df..00000000000000 --- a/src/content/partials/ssl/client-cert-shared.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -{} - ---- - -:::caution - - -Since Cloudflare validates client certificates with one CA, set at account level, these certificates can be used for validation across multiple zones, as long as the zones are under the same account and mTLS has been enabled for the requested hosts. -This means that (a) if you [bring your own CA](/ssl/client-certificates/byo-ca/), you can associate it with hosts in different zones and (b) if you use Cloudflare Managed CA, this is the default behavior. - - -::: From c63428b6ee2b6e3649c4640d105e49dac062438d Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Tue, 1 Jul 2025 18:18:27 +0100 Subject: [PATCH 07/33] Add placeholder text and hyperlinks under #use-cases --- src/content/docs/ssl/client-certificates/index.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index adedc3196eabe1..465ecbc47315c2 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -28,4 +28,11 @@ If you use the Cloudflare-managed CA, client certificates that you create can be Bring your own CA (BYOCA) is API-only and certificates or host associations will **not** show up on your dashboard. ::: -## Use cases \ No newline at end of file +## Use cases + +(Intro blurb and new link out to LP) + +- [App security implementation guide](/learning-paths/mtls/mtls-app-security/) +- [API Shield](/api-shield/security/mtls/configure/) +- [Access](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) +- [Workers](/workers/runtime-apis/bindings/mtls/) \ No newline at end of file From 0279c863b3769176f7f8c1ce724d0e20e55328e5 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 08:27:05 +0100 Subject: [PATCH 08/33] Make CA distiction less wordy and use parallelism for clarity --- src/content/docs/ssl/client-certificates/index.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 465ecbc47315c2..caac6eefb90d31 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -20,13 +20,12 @@ For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning ## Scope -Cloudflare validates client certificates with one CA, 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 account and mTLS has been enabled for the requested hosts (`host.example.com`). +Cloudflare validates client certificates with one CA, 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 mTLS has been enabled for the requested hosts (`host.example.com`). -If you use the Cloudflare-managed CA, client certificates that you create can be used with hosts in any zone/domain that belongs to your Cloudflare account. If you [bring your own CA](/ssl/client-certificates/byo-ca/), it will be set at account level and you can associate it with hosts in different zones/domains. +The account-level CA can be either: -:::note -Bring your own CA (BYOCA) is API-only and certificates or host associations will **not** show up on your dashboard. -::: +- The Cloudflare-managed CA: This is the default option. Certificates and hostname associations are listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). +- A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostnames associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). ## Use cases From e2821fa8a748b7c1dfa036543fa8c88c67e6fe03 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 14:30:40 +0100 Subject: [PATCH 09/33] Add horizontal break line and DirectoryListing to index.mdx --- .../docs/ssl/client-certificates/index.mdx | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index caac6eefb90d31..54c14a9888916c 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -8,9 +8,9 @@ description: Use Cloudflare public key infrastructure (PKI) to create client cer --- -import { GlossaryDefinition, Render } from "~/components"; +import { GlossaryDefinition, Render, DirectoryListing } from "~/components"; -Use Cloudflare public key infrastructure (PKI) to create client certificates, or [bring your own CA for mTLS](/ssl/client-certificates/byo-ca/). +Use Cloudflare's public key infrastructure (PKI) to create client certificates, or [bring your own CA for mTLS](/ssl/client-certificates/byo-ca/). @@ -18,6 +18,8 @@ Use Cloudflare public key infrastructure (PKI) to create client certificates, or For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning-paths/mtls/concepts/). ::: +--- + ## Scope Cloudflare validates client certificates with one CA, 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 mTLS has been enabled for the requested hosts (`host.example.com`). @@ -27,6 +29,8 @@ The account-level CA can be either: - The Cloudflare-managed CA: This is the default option. Certificates and hostname associations are listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). - A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostnames associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). +--- + ## Use cases (Intro blurb and new link out to LP) @@ -34,4 +38,10 @@ The account-level CA can be either: - [App security implementation guide](/learning-paths/mtls/mtls-app-security/) - [API Shield](/api-shield/security/mtls/configure/) - [Access](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) -- [Workers](/workers/runtime-apis/bindings/mtls/) \ No newline at end of file +- [Workers](/workers/runtime-apis/bindings/mtls/) + +--- + +## Further resources + + \ No newline at end of file From 7742b1d5821b889d8a3f6393aab50da3248c19cc Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 14:34:59 +0100 Subject: [PATCH 10/33] Review links out to create-a-client-certificate --- src/content/notifications/index.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/notifications/index.yaml b/src/content/notifications/index.yaml index d5f556608d24da..05fcc167927a2e 100644 --- a/src/content/notifications/index.yaml +++ b/src/content/notifications/index.yaml @@ -394,7 +394,7 @@ entries: availability: |- [Bring your own CA](/ssl/client-certificates/byo-ca/). - The mTLS Certificate Store refers to customer uploaded certificates and does not include client certificates generated with the [Cloudflare CA](/ssl/client-certificates/create-a-client-certificate/). + The mTLS Certificate Store refers to customer uploaded certificates and does not include client certificates generated with the [Cloudflare CA](/ssl/client-certificates/#scope). associatedProducts: SSL/TLS nextSteps: Upload a renewed certificate. otherFilters: None. From c3045f74562f2337e6bdeb90940a772538d70630 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 14:48:25 +0100 Subject: [PATCH 11/33] Revise create-a-client-cert for wordiness and consistency with LP --- .../create-a-client-certificate.mdx | 24 +++++++------------ 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index aa02a0aa88f5dd..b133d33c5650c8 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -8,26 +8,20 @@ sidebar: To create a client certificate in the Cloudflare dashboard: -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and application. +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and zone/domain. 2. Go to **SSL** > **Client Certificates**. -3. Select **Create Certificate**. +3. Select **Create Certificate** and fill in the required fields. You can choose one of the following options: - :::caution +- Generate a private key and Certificate Signing Request (CSR) with Cloudflare. +- Use your own private key and CSR which allows you to also [label client certificates](/ssl/client-certificates/label-client-certificate/). - By default, client certificates are issued by a Cloudflare Managed CA. Cloudflare generates a unique CA for each account. +:::note +Client certificates created on the dashboard are issued by a [Cloudflare-managed CA](/ssl/client-certificates/#scope). If you need to use certificates issued by another CA, use the API to [bring your own CA](/ssl/client-certificates/byo-ca/). +::: - 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/). - ::: +5. Select a value for **Certificate Validity**, and choose **Create** to confirm. -4. For **Private key type**, select a value. - -5. For **Certificate Validity**, select a value. The default value is 10 years. - -6. Select **Create**. - -7. To copy the certificate or private key to your clipboard, use the **click to copy** link. - -8. To close the dialog, select **OK**. +6. Make sure to copy the certificate and private key. Select **OK** to go back to your client certificates list. ## Next steps From 05d92e478a5f1d43ff484b430281ee3ea7b54bc8 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 15:05:25 +0100 Subject: [PATCH 12/33] Text refinement and remove Workers from #next-steps --- .../create-a-client-certificate.mdx | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index b133d33c5650c8..ca5ed465056ca9 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -6,26 +6,37 @@ sidebar: --- -To create a client certificate in the Cloudflare dashboard: +import { Details } from "~/components"; + +To create a client certificate on the Cloudflare dashboard: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and zone/domain. 2. Go to **SSL** > **Client Certificates**. 3. Select **Create Certificate** and fill in the required fields. You can choose one of the following options: - Generate a private key and Certificate Signing Request (CSR) with Cloudflare. -- Use your own private key and CSR which allows you to also [label client certificates](/ssl/client-certificates/label-client-certificate/). +- Use your own private key and CSR. This option allows you to also [label client certificates](/ssl/client-certificates/label-client-certificate/). + +
+ + To generate and use your own CSR, you can run a command like the following: + + ```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' + ``` + +
:::note -Client certificates created on the dashboard are issued by a [Cloudflare-managed CA](/ssl/client-certificates/#scope). If you need to use certificates issued by another CA, use the API to [bring your own CA](/ssl/client-certificates/byo-ca/). +Client certificates created on the dashboard are issued by [Cloudflare-managed CA](/ssl/client-certificates/#scope). If you need to use certificates issued by another CA, use the API to [bring your own CA](/ssl/client-certificates/byo-ca/) instead. ::: -5. Select a value for **Certificate Validity**, and choose **Create** to confirm. - -6. Make sure to copy the certificate and private key. Select **OK** to go back to your client certificates list. +4. Select a value for **Certificate Validity**, and choose **Create**. +5. Make sure to copy the certificate and private key. +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 [learning path](/learning-paths/mtls/concepts/) for further context. \ No newline at end of file From 15fc64422af8a311008772da3f99cbcb392feb8b Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 15:14:25 +0100 Subject: [PATCH 13/33] Reorder pages --- .../configure-your-mobile-app-or-iot-device.mdx | 2 +- src/content/docs/ssl/client-certificates/troubleshooting.mdx | 2 +- src/content/docs/ssl/client-certificates/zero-trust-mtls.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/configure-your-mobile-app-or-iot-device.mdx b/src/content/docs/ssl/client-certificates/configure-your-mobile-app-or-iot-device.mdx index 4c9a4093e3f8d0..87c64e2c5792e9 100644 --- a/src/content/docs/ssl/client-certificates/configure-your-mobile-app-or-iot-device.mdx +++ b/src/content/docs/ssl/client-certificates/configure-your-mobile-app-or-iot-device.mdx @@ -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/). diff --git a/src/content/docs/ssl/client-certificates/troubleshooting.mdx b/src/content/docs/ssl/client-certificates/troubleshooting.mdx index 560beda9311e83..2a7eeb76b86373 100644 --- a/src/content/docs/ssl/client-certificates/troubleshooting.mdx +++ b/src/content/docs/ssl/client-certificates/troubleshooting.mdx @@ -2,7 +2,7 @@ title: Troubleshooting pcx_content_type: troubleshooting sidebar: - order: 9 + order: 10 head: - tag: title content: Troubleshooting client certificates diff --git a/src/content/docs/ssl/client-certificates/zero-trust-mtls.mdx b/src/content/docs/ssl/client-certificates/zero-trust-mtls.mdx index 33da597835800c..677e7b99b476c9 100644 --- a/src/content/docs/ssl/client-certificates/zero-trust-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/zero-trust-mtls.mdx @@ -3,6 +3,6 @@ pcx_content_type: navigation title: mTLS for Zero Trust external_link: /cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/ sidebar: - order: 10 + order: 14 --- From 110bc83073f54c11d9ec10cdab585c4a59d56fa4 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 15:29:04 +0100 Subject: [PATCH 14/33] Separate forward option from enable-mtls page --- .../mtls/mtls-app-security/related-features.mdx | 2 +- .../docs/ssl/client-certificates/enable-mtls.mdx | 6 +----- .../forward-a-client-certificate.mdx | 13 +++++++++++++ 3 files changed, 15 insertions(+), 6 deletions(-) create mode 100644 src/content/docs/ssl/client-certificates/forward-a-client-certificate.mdx diff --git a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx index 03dcfe1afe6923..799a03834d1a30 100644 --- a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx @@ -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 diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index e0ffec87ca7e04..b381f7e17782f8 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -10,9 +10,7 @@ import { Render } from "~/components" 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: +To enable mTLS for a host from the Cloudflare dashboard: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and application. 2. Go to **SSL** > **Client Certificates**. @@ -23,5 +21,3 @@ To enable mutual Transport Layer Security (mTLS) for a host from the Cloudflare 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. - - diff --git a/src/content/docs/ssl/client-certificates/forward-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/forward-a-client-certificate.mdx new file mode 100644 index 00000000000000..4958c7c91a7b26 --- /dev/null +++ b/src/content/docs/ssl/client-certificates/forward-a-client-certificate.mdx @@ -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"; + + \ No newline at end of file From df598ebb04aa4e848c31c1dacc748a43476e1160 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Wed, 2 Jul 2025 16:02:39 +0100 Subject: [PATCH 15/33] Adjust heading and hyperlinks text --- src/content/docs/ssl/client-certificates/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 54c14a9888916c..faa13b964fd1da 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -35,13 +35,13 @@ The account-level CA can be either: (Intro blurb and new link out to LP) -- [App security implementation guide](/learning-paths/mtls/mtls-app-security/) -- [API Shield](/api-shield/security/mtls/configure/) -- [Access](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) -- [Workers](/workers/runtime-apis/bindings/mtls/) +- [Application security](/learning-paths/mtls/mtls-app-security/) +- [mTLS Access integration](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) +- [mTLS with API Shield](/api-shield/security/mtls/configure/) +- [mTLS Workers binding](/workers/runtime-apis/bindings/mtls/) --- -## Further resources +## Resources \ No newline at end of file From 721562eca6af1f1ed347e95dec9803ab20a65a4d Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 3 Jul 2025 12:17:41 +0100 Subject: [PATCH 16/33] Explicitly call out only one CA per hostname association --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index b80ec81dac42c5..27c3980060912e 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -64,8 +64,7 @@ Bring your own CA (BYOCA) is especially useful if you already have mTLS implemen * Indicate the certificate ID obtained from the previous step. :::caution - - If no `mtls_certificate_id` is provided, the action will be performed against a Cloudflare Managed CA. + If no `mtls_certificate_id` is provided, the action will be performed against the [Cloudflare Managed CA](/ssl/client-certificates/#scope). Also, a single hostname can only be associated with one CA at a time. ::: 4. (Optional) Since this process is API-only, and hostnames that use your uploaded CA certificate **are not** listed on the dashboard, you can make a [GET request](#list-ca-hostname-associations) to confirm the CA hostname associations. From 5229afc905325a6b596415db9b448ea75bccf04d Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 3 Jul 2025 12:54:15 +0100 Subject: [PATCH 17/33] Revert "Explicitly call out only one CA per hostname association" This reverts commit 721562eca6af1f1ed347e95dec9803ab20a65a4d. --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index 27c3980060912e..b80ec81dac42c5 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -64,7 +64,8 @@ Bring your own CA (BYOCA) is especially useful if you already have mTLS implemen * Indicate the certificate ID obtained from the previous step. :::caution - If no `mtls_certificate_id` is provided, the action will be performed against the [Cloudflare Managed CA](/ssl/client-certificates/#scope). Also, a single hostname can only be associated with one CA at a time. + + If no `mtls_certificate_id` is provided, the action will be performed against a Cloudflare Managed CA. ::: 4. (Optional) Since this process is API-only, and hostnames that use your uploaded CA certificate **are not** listed on the dashboard, you can make a [GET request](#list-ca-hostname-associations) to confirm the CA hostname associations. From 1d098799bbf770f5f3d42255b65a015c2f02b5fc Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Thu, 3 Jul 2025 13:07:44 +0100 Subject: [PATCH 18/33] Add intro paragraph and change h2 to how-it-works --- .../client-certificates/create-a-client-certificate.mdx | 2 +- src/content/docs/ssl/client-certificates/index.mdx | 8 +++++--- src/content/notifications/index.yaml | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index ca5ed465056ca9..f57d318898395a 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -28,7 +28,7 @@ To create a client certificate on the Cloudflare dashboard: :::note -Client certificates created on the dashboard are issued by [Cloudflare-managed CA](/ssl/client-certificates/#scope). If you need to use certificates issued by another CA, use the API to [bring your own CA](/ssl/client-certificates/byo-ca/) instead. +Client certificates created on the dashboard are issued by [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. ::: 4. Select a value for **Certificate Validity**, and choose **Create**. diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index faa13b964fd1da..8b63a55da61517 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -20,11 +20,13 @@ For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning --- -## Scope +## How it works -Cloudflare validates client certificates with one CA, 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 mTLS has been enabled for the requested hosts (`host.example.com`). +Client certificates issued from a given CA are installed on client devices that should be granted access. Then, for any host that has [mTLS enabled](/ssl/client-certificates/enable-mtls/), Cloudflare requires a client certificate from the client trying to access the hostname. -The account-level CA can be either: +The client certificate is then validated 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 mTLS has been enabled for the requested hosts (`host.example.com`). + +The account-level CAs can be: - The Cloudflare-managed CA: This is the default option. Certificates and hostname associations are listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). - A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostnames associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). diff --git a/src/content/notifications/index.yaml b/src/content/notifications/index.yaml index 05fcc167927a2e..04b87c5d8df1cc 100644 --- a/src/content/notifications/index.yaml +++ b/src/content/notifications/index.yaml @@ -394,7 +394,7 @@ entries: availability: |- [Bring your own CA](/ssl/client-certificates/byo-ca/). - The mTLS Certificate Store refers to customer uploaded certificates and does not include client certificates generated with the [Cloudflare CA](/ssl/client-certificates/#scope). + The mTLS Certificate Store refers to customer uploaded certificates and does not include client certificates generated with the [Cloudflare CA](/ssl/client-certificates/#how-it-works). associatedProducts: SSL/TLS nextSteps: Upload a renewed certificate. otherFilters: None. From 24744bb6e722c20533eadc4081069318d02a7668 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 4 Jul 2025 12:04:37 +0100 Subject: [PATCH 19/33] Text review --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 4 ++-- .../docs/ssl/client-certificates/enable-mtls.mdx | 13 +++++++++---- src/content/docs/ssl/client-certificates/index.mdx | 6 +++--- 3 files changed, 14 insertions(+), 9 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index b80ec81dac42c5..13510e2d077a88 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -12,9 +12,9 @@ description: Cloudflare mTLS now supports client certificates that have not been import { Render, APIRequest } from "~/components" -This page explains how you can manage client certificates that have not been issued by Cloudflare CA. For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning-paths/mtls/concepts/). +This page explains how you can manage client certificates that have not been issued by Cloudflare CA. For a broader overview of mTLS at Cloudflare, refer to [learning paths](/learning-paths/mtls/concepts/). -Bring your own CA (BYOCA) 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 diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index b381f7e17782f8..e2cdce24e2e083 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -12,11 +12,16 @@ You can enable mutual Transport Layer Security (mTLS) for any hostname. To enable mTLS for a host from the Cloudflare dashboard: -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and application. +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and domain. 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**. +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, so if you want to enable mTLS for `abc.example.com`, you only need to type `abc`. +::: +5. Select **Save** to confirm. + +## Next steps 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. diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 8b63a55da61517..ef276cf5685e12 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -22,14 +22,14 @@ For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning ## How it works -Client certificates issued from a given CA are installed on client devices that should be granted access. Then, for any host that has [mTLS enabled](/ssl/client-certificates/enable-mtls/), Cloudflare requires a client certificate from the client trying to access the hostname. +Client certificates issued from a given CA are installed on client devices that should be granted access. Then, for any host that has [mTLS enabled](/ssl/client-certificates/enable-mtls/), Cloudflare - acting as the server in this case - requires a certificate from the client trying to access the hostname. -The client certificate is then validated 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 mTLS has been enabled for the requested hosts (`host.example.com`). +Cloudflare then validates the client certificate 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 mTLS has been enabled for the requested hosts (`host.example.com`). The account-level CAs can be: - The Cloudflare-managed CA: This is the default option. Certificates and hostname associations are listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). -- A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostnames associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). +- A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostname associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). --- From 2048b87f1c147729f57cae9324a7efa8eeb14542 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 4 Jul 2025 12:13:53 +0100 Subject: [PATCH 20/33] Review enable-mtls leveraging LP and new content in this PR --- .../docs/ssl/client-certificates/enable-mtls.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index e2cdce24e2e083..264fae10c4b4a4 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -21,8 +21,19 @@ The domain (`example.com`) is automatically appended for you, so if you want to ::: 5. Select **Save** to confirm. +## CAs in use + +As explained in [Overview](/ssl/client-certificates/#how-it-works), Cloudflare validates the client certificate 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. + +:::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. +::: + ## Next steps -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. +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 [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. - + \ No newline at end of file From c4a0c1d187ea83a976afeb762292e679ab55a05f Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 4 Jul 2025 14:09:03 +0100 Subject: [PATCH 21/33] Replace placeholder in #use-cases and add more info about workers --- .../docs/ssl/client-certificates/index.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index ef276cf5685e12..038e01cc91bcd5 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -35,13 +35,24 @@ The account-level CAs can be: ## Use cases -(Intro blurb and new link out to LP) +As explained in the [mTLS learning path](/learning-paths/mtls/concepts/), there are different use cases and implementation options for mTLS. Consider the following links for specific guidance. - [Application security](/learning-paths/mtls/mtls-app-security/) -- [mTLS Access integration](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) +- [mTLS for Zero Trust](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) (Cloudflare Access integration) - [mTLS with API Shield](/api-shield/security/mtls/configure/) - [mTLS Workers binding](/workers/runtime-apis/bindings/mtls/) +### mTLS and Workers + +Use the [mTLS Workers binding](/workers/runtime-apis/bindings/mtls/) when you need your worker to present a client certificate to an external service. To authenticate requests from a client to your worker instead, refer to [SSL/TLS > Client certificates](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/) and the regular [mTLS for application security](/learning-paths/mtls/mtls-app-security/) implementation. + +```mermaid +flowchart LR + accTitle: mTLS from client to worker versus mTLS from worker to external service + accDescr: Diagram showing two different implementations that can be considered for mTLS with Cloudflare Workers. + A[Client] <--App security mTLS--> B((Cloudflare))<--mTLS worker binding--> C[(External service)] +``` + --- ## Resources From a78c35a3888fdd9d4fd8cb944484ed4c3022d93f Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 4 Jul 2025 14:17:46 +0100 Subject: [PATCH 22/33] General text review --- .../client-certificates/create-a-client-certificate.mdx | 8 ++++---- src/content/docs/ssl/client-certificates/enable-mtls.mdx | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index f57d318898395a..6de598a8562446 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -14,8 +14,8 @@ To create a client certificate on the Cloudflare dashboard: 2. Go to **SSL** > **Client Certificates**. 3. Select **Create Certificate** and fill in the required fields. You can choose one of the following options: -- 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/). + - 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/).
@@ -28,11 +28,11 @@ To create a client certificate on the Cloudflare dashboard:
:::note -Client certificates created on the dashboard are issued by [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. +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. ::: 4. Select a value for **Certificate Validity**, and choose **Create**. -5. Make sure to copy the certificate and private key. +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 diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index 264fae10c4b4a4..a9275825d22929 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -17,13 +17,13 @@ To enable mTLS for a host from the Cloudflare dashboard: 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, so if you want to enable mTLS for `abc.example.com`, you only need to type `abc`. +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. ## CAs in use -As explained in [Overview](/ssl/client-certificates/#how-it-works), Cloudflare validates the client certificate 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. +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. :::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. From 9697c52c1680b31b4292c039d14fc8b39a244030 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 4 Jul 2025 14:52:45 +0100 Subject: [PATCH 23/33] Explicitly mention and link to BYOCA from LP and #use-cases --- .../docs/learning-paths/mtls/mtls-app-security/index.mdx | 2 +- .../docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx | 2 +- src/content/docs/ssl/client-certificates/index.mdx | 2 ++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx b/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx index 778ecade902c6d..57bfdf9c38e7b5 100644 --- a/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx @@ -10,7 +10,7 @@ This implementation requires an active [Zone](/fundamentals/concepts/accounts-an API Shield is not required to use mTLS.
-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. Cloudflare generates a unique CA for each customer account, meaning that Client Certificates all validate against an account-level Cloudflare CA. If you have an Enterprise account, you also have the option to [bring your own CA](/ssl/client-certificates/byo-ca/). ::: ## 1. Enable mTLS diff --git a/src/content/docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx b/src/content/docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx index 8a105b074bdc54..5002b5e6ba098d 100644 --- a/src/content/docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx @@ -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 diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 038e01cc91bcd5..311afe6b8ea2fc 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -42,6 +42,8 @@ As explained in the [mTLS learning path](/learning-paths/mtls/concepts/), there - [mTLS with API Shield](/api-shield/security/mtls/configure/) - [mTLS Workers binding](/workers/runtime-apis/bindings/mtls/) +Apart from the mTLS Workers binding, any of the above implementations can use your own CA instead of the Cloudflare-managed one. Refer to [Bring your own CA](/ssl/client-certificates/byo-ca/). + ### mTLS and Workers Use the [mTLS Workers binding](/workers/runtime-apis/bindings/mtls/) when you need your worker to present a client certificate to an external service. To authenticate requests from a client to your worker instead, refer to [SSL/TLS > Client certificates](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/) and the regular [mTLS for application security](/learning-paths/mtls/mtls-app-security/) implementation. From 9372a3d05026b873ba38e0d2cc76eee5ca8dd566 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 7 Jul 2025 14:03:13 +0100 Subject: [PATCH 24/33] Fix broken anchors --- .../docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx | 2 +- .../learning-paths/mtls/mtls-app-security/related-features.mdx | 2 +- src/content/docs/learning-paths/mtls/mtls-workers/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx b/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx index d045e13d80ac06..fcc1c679a80e0f 100644 --- a/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx +++ b/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx @@ -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.

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. | diff --git a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx index 799a03834d1a30..22c2dffc70b51e 100644 --- a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx @@ -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, the first 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) diff --git a/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx b/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx index ad2edc8d907576..88931f32ff341c 100644 --- a/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx @@ -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): ```js From 7baf1966e929711fd2ea9ad2dbe1ebaeb9ce0893 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 7 Jul 2025 14:12:50 +0100 Subject: [PATCH 25/33] Fix info on requests including Cf-Client-Cert headers --- src/content/partials/ssl/forward-client-certificate.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/ssl/forward-client-certificate.mdx b/src/content/partials/ssl/forward-client-certificate.mdx index d9f5687fccee5a..88951c845bdef2 100644 --- a/src/content/partials/ssl/forward-client-certificate.mdx +++ b/src/content/partials/ssl/forward-client-certificate.mdx @@ -36,7 +36,7 @@ The most common approach to forwarding a certificate is to use the Cloudflare AP }} /> -Once `client_certificate_forwarding` is set to `true`, the first request of an mTLS connection will now include the following headers: +Once `client_certificate_forwarding` is set to `true`, every request within an mTLS connection will now include the following headers: * `Cf-Client-Cert-Der-Base64` * `Cf-Client-Cert-Sha256` From a6a170f211471b180926c77be62214a6caf4ecbe Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 7 Jul 2025 15:00:03 +0100 Subject: [PATCH 26/33] Text review --- .../ssl/client-certificates/create-a-client-certificate.mdx | 2 +- src/content/docs/ssl/client-certificates/enable-mtls.mdx | 2 +- src/content/docs/ssl/client-certificates/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index 6de598a8562446..17cb6df90e06e5 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -11,7 +11,7 @@ import { Details } from "~/components"; To create a client certificate on the Cloudflare dashboard: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and zone/domain. -2. Go to **SSL** > **Client Certificates**. +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: - Generate a private key and Certificate Signing Request (CSR) with Cloudflare. diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index a9275825d22929..a3c2570e1e4290 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -13,7 +13,7 @@ You can enable mutual Transport Layer Security (mTLS) for any hostname. To enable 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** > **Client Certificates**. +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 diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index 311afe6b8ea2fc..e3e6f5c9f6451f 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -29,7 +29,7 @@ Cloudflare then validates the client certificate against CAs set at account leve The account-level CAs can be: - The Cloudflare-managed CA: This is the default option. Certificates and hostname associations are listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). -- A [BYOCA](/ssl/client-certificates/byo-ca/) certificate: This is an API-only option, available on Enterprise accounts. Certificates and hostname associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). +- [BYOCA](/ssl/client-certificates/byo-ca/) certificates: This is an API-only option, available on Enterprise accounts. Certificates and hostname associations are **not** listed on your [dashboard](https://dash.cloudflare.com/?to=/:account/:zone/ssl-tls/client-certificates/). --- From d61311f2c6082ef54072373fc14de553b512cb37 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 7 Jul 2025 16:27:17 +0100 Subject: [PATCH 27/33] Add section about multiple CAs for the same hostname --- .../docs/ssl/client-certificates/byo-ca.mdx | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index 13510e2d077a88..c70bb5ad6e7dad 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -10,7 +10,7 @@ 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 client certificates that have not been issued by Cloudflare CA. For a broader overview of mTLS at Cloudflare, refer to [learning paths](/learning-paths/mtls/concepts/). @@ -78,6 +78,42 @@ Bring your own CA (BYOCA) is especially useful if you already have mTLS implemen "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): + + + +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. + + + +1. [List the hostname associations](/api/resources/certificate_authorities/subresources/hostname_associations/methods/get/) **without** the `mtls_certificate_id` parameter. + + + +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. + +"] + }} +/> + + + ## 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. From 2edfb5525e344e89505278c075850427dc6ab853 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 7 Jul 2025 17:01:59 +0100 Subject: [PATCH 28/33] Remove DirectoryListing from overview page --- src/content/docs/ssl/client-certificates/index.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index e3e6f5c9f6451f..d1baf233125009 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -53,10 +53,4 @@ flowchart LR accTitle: mTLS from client to worker versus mTLS from worker to external service accDescr: Diagram showing two different implementations that can be considered for mTLS with Cloudflare Workers. A[Client] <--App security mTLS--> B((Cloudflare))<--mTLS worker binding--> C[(External service)] -``` - ---- - -## Resources - - \ No newline at end of file +``` \ No newline at end of file From 835fc832a2c5e8f1534dad418e6f29d8c6d867ca Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Fri, 18 Jul 2025 10:26:13 +0100 Subject: [PATCH 29/33] Remove additional warning from enable-mtls and delete partial --- .../docs/api-shield/security/mtls/configure.mdx | 7 ++++++- .../docs/ssl/client-certificates/enable-mtls.mdx | 4 +--- .../partials/ssl/cloudflare-managed-client-cert.mdx | 11 ----------- 3 files changed, 7 insertions(+), 15 deletions(-) delete mode 100644 src/content/partials/ssl/cloudflare-managed-client-cert.mdx diff --git a/src/content/docs/api-shield/security/mtls/configure.mdx b/src/content/docs/api-shield/security/mtls/configure.mdx index f0fb4c4ad3840f..3f136841ed7090 100644 --- a/src/content/docs/api-shield/security/mtls/configure.mdx +++ b/src/content/docs/api-shield/security/mtls/configure.mdx @@ -23,7 +23,12 @@ Before you can protect your API or web application with mTLS rules, you need to: - +:::caution + +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](/ssl/client-certificates/byo-ca/). +::: ## Create an mTLS rule via the Cloudflare dashboard diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index a3c2570e1e4290..6659db07a31fae 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -34,6 +34,4 @@ If you need to use your own CA (instead of the Cloudflare Managed CA), refer to 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 [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. - - \ No newline at end of file +- 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. \ No newline at end of file diff --git a/src/content/partials/ssl/cloudflare-managed-client-cert.mdx b/src/content/partials/ssl/cloudflare-managed-client-cert.mdx deleted file mode 100644 index 0f978a5667c9be..00000000000000 --- a/src/content/partials/ssl/cloudflare-managed-client-cert.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -{} - ---- - -:::caution - -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](/ssl/client-certificates/byo-ca/). -::: From 6ed861457668826679d92d5fc310b1317823eda1 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 21 Jul 2025 15:11:00 +0100 Subject: [PATCH 30/33] Apply changes following PM review --- src/content/docs/api-shield/security/mtls/configure.mdx | 4 +--- .../mtls/mtls-app-security/related-features.mdx | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/api-shield/security/mtls/configure.mdx b/src/content/docs/api-shield/security/mtls/configure.mdx index 3f136841ed7090..f1bcba7c83b4e8 100644 --- a/src/content/docs/api-shield/security/mtls/configure.mdx +++ b/src/content/docs/api-shield/security/mtls/configure.mdx @@ -25,9 +25,7 @@ Before you can protect your API or web application with mTLS rules, you need to: :::caution -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](/ssl/client-certificates/byo-ca/). +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 diff --git a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx index 22c2dffc70b51e..41418536d3587b 100644 --- a/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx @@ -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/forward-a-client-certificate/#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) From 88d28b30b6abfce9f6bad246af32d44dfe74f6a3 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Mon, 21 Jul 2025 15:24:39 +0100 Subject: [PATCH 31/33] Remove remaining mention of account-specific CA --- .../docs/learning-paths/mtls/mtls-app-security/index.mdx | 2 +- src/content/partials/ssl/forward-client-certificate.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx b/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx index 57bfdf9c38e7b5..a47ea43421266e 100644 --- a/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx @@ -10,7 +10,7 @@ This implementation requires an active [Zone](/fundamentals/concepts/accounts-an API Shield is not required to use mTLS.
-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. If you have an Enterprise account, you also have the option to [bring your own CA](/ssl/client-certificates/byo-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 diff --git a/src/content/partials/ssl/forward-client-certificate.mdx b/src/content/partials/ssl/forward-client-certificate.mdx index 88951c845bdef2..b366799d7eb4cb 100644 --- a/src/content/partials/ssl/forward-client-certificate.mdx +++ b/src/content/partials/ssl/forward-client-certificate.mdx @@ -36,7 +36,7 @@ The most common approach to forwarding a certificate is to use the Cloudflare AP }} /> -Once `client_certificate_forwarding` is set to `true`, every request within an mTLS connection will now include the following headers: +Once `client_certificate_forwarding` is set to `true`, every request within an mTLS connection will now include the following headers: * `Cf-Client-Cert-Der-Base64` * `Cf-Client-Cert-Sha256` From 299cbdfd821a92d5ddb6629617332929efb33b8e Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro <62246989+RebeccaTamachiro@users.noreply.github.com> Date: Mon, 21 Jul 2025 17:01:50 +0100 Subject: [PATCH 32/33] Improve consistency for hyperlinks to learning path Co-authored-by: marciocloudflare <83226960+marciocloudflare@users.noreply.github.com> --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 2 +- .../ssl/client-certificates/create-a-client-certificate.mdx | 2 +- src/content/docs/ssl/client-certificates/enable-mtls.mdx | 2 +- src/content/docs/ssl/client-certificates/index.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index c70bb5ad6e7dad..3d5f474f6c535b 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -12,7 +12,7 @@ description: Cloudflare mTLS now supports client certificates that have not been import { Render, APIRequest, Tabs, TabItem } from "~/components" -This page explains how you can manage client certificates that have not been issued by Cloudflare CA. For a broader overview of mTLS at Cloudflare, refer to [learning paths](/learning-paths/mtls/concepts/). +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/). 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. diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index 17cb6df90e06e5..df3d03bb815b23 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -39,4 +39,4 @@ Client certificates created on the dashboard are issued by a [Cloudflare-managed 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. -Refer to our [learning path](/learning-paths/mtls/concepts/) for further context. \ No newline at end of file +Refer to our [mtLS at Cloudflare learning path](/learning-paths/mtls/concepts/) for further context. \ No newline at end of file diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index 6659db07a31fae..595618d0824863 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -33,5 +33,5 @@ If you need to use your own CA (instead of the Cloudflare Managed CA), refer to 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 [learning path](/learning-paths/mtls/mtls-app-security/#3-validate-the-client-certificate-in-the-waf) for further guidance. +- 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. \ No newline at end of file diff --git a/src/content/docs/ssl/client-certificates/index.mdx b/src/content/docs/ssl/client-certificates/index.mdx index d1baf233125009..2a52313b789da5 100644 --- a/src/content/docs/ssl/client-certificates/index.mdx +++ b/src/content/docs/ssl/client-certificates/index.mdx @@ -15,7 +15,7 @@ Use Cloudflare's public key infrastructure (PKI) to create client certificates, :::note[mTLS at Cloudflare] -For a broader overview of mTLS at Cloudflare refer to [learning paths](/learning-paths/mtls/concepts/). +For a broader overview, refer to the [mTLS at Cloudflare learning path](/learning-paths/mtls/concepts/). ::: --- From 07054bde8d27a1e57e527339d2709b872aaeb459 Mon Sep 17 00:00:00 2001 From: Rebecca Tamachiro Date: Mon, 21 Jul 2025 17:04:29 +0100 Subject: [PATCH 33/33] Fix capitalization --- src/content/docs/ssl/client-certificates/byo-ca.mdx | 2 +- .../ssl/client-certificates/create-a-client-certificate.mdx | 2 +- src/content/docs/ssl/client-certificates/enable-mtls.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/ssl/client-certificates/byo-ca.mdx b/src/content/docs/ssl/client-certificates/byo-ca.mdx index 3d5f474f6c535b..5b0dd9a34810c2 100644 --- a/src/content/docs/ssl/client-certificates/byo-ca.mdx +++ b/src/content/docs/ssl/client-certificates/byo-ca.mdx @@ -12,7 +12,7 @@ description: Cloudflare mTLS now supports client certificates that have not been import { Render, APIRequest, Tabs, TabItem } from "~/components" -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 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/). 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. diff --git a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx index df3d03bb815b23..17d7ac6ff44f60 100644 --- a/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx +++ b/src/content/docs/ssl/client-certificates/create-a-client-certificate.mdx @@ -39,4 +39,4 @@ Client certificates created on the dashboard are issued by a [Cloudflare-managed 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. -Refer to our [mtLS at Cloudflare learning path](/learning-paths/mtls/concepts/) for further context. \ No newline at end of file +Refer to our [mTLS at Cloudflare learning path](/learning-paths/mtls/concepts/) for further context. \ No newline at end of file diff --git a/src/content/docs/ssl/client-certificates/enable-mtls.mdx b/src/content/docs/ssl/client-certificates/enable-mtls.mdx index 595618d0824863..ddee6e4700ea5a 100644 --- a/src/content/docs/ssl/client-certificates/enable-mtls.mdx +++ b/src/content/docs/ssl/client-certificates/enable-mtls.mdx @@ -33,5 +33,5 @@ If you need to use your own CA (instead of the Cloudflare Managed CA), refer to 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 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. \ No newline at end of file