[SSL] Revise and consolidate client certs content (#23365)

* Add (mTLS) to page title

* Review glossary entry and apply mTLS definition throughout

* Link to BYOCA and learning path from client certs landing page

* Review content in byo-ca and adjust page intro

* Remove step-like sections and add new proposed h2s

* Fill in Scope section and delete redundant partial

* Add placeholder text and hyperlinks under #use-cases

* Make CA distiction less wordy and use parallelism for clarity

* Add horizontal break line and DirectoryListing to index.mdx

* Review links out to create-a-client-certificate

* Revise create-a-client-cert for wordiness and consistency with LP

* Text refinement and remove Workers from #next-steps

* Reorder pages

* Separate forward option from enable-mtls page

* Adjust heading and hyperlinks text

* Explicitly call out only one CA per hostname association

* Revert "Explicitly call out only one CA per hostname association"

This reverts commit 721562e.

* Add intro paragraph and change h2 to how-it-works

* Text review

* Review enable-mtls leveraging LP and new content in this PR

* Replace placeholder in #use-cases and add more info about workers

* General text review

* Explicitly mention and link to BYOCA from LP and #use-cases

* Fix broken anchors

* Fix info on requests including Cf-Client-Cert headers

* Text review

* Add section about multiple CAs for the same hostname

* Remove DirectoryListing from overview page

* Remove additional warning from enable-mtls and delete partial

* Apply changes following PM review

* Remove remaining mention of account-specific CA

* Improve consistency for hyperlinks to learning path

Co-authored-by: marciocloudflare <[email protected]>

* Fix capitalization

---------

Co-authored-by: marciocloudflare <[email protected]>

Author: 2 people

src/content/docs/api-shield/security/mtls/configure.mdx

@@ -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
 

src/content/docs/api-shield/security/mtls/index.mdx

@@ -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)
 

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";
+
+<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.
 

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

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

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
 
@@ -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)

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

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):
 
 <Tabs> <TabItem label="Module Worker" icon="seti:javascript">
 ```js

src/content/docs/ssl/client-certificates/byo-ca.mdx

@@ -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.

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/).