diff --git a/src/assets/images/learning-paths/mtls/certification-revocation-custom-rule.png b/src/assets/images/learning-paths/mtls/certification-revocation-custom-rule.png new file mode 100644 index 00000000000000..33a7e8e072d2d9 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/certification-revocation-custom-rule.png differ diff --git a/src/assets/images/learning-paths/mtls/configure-waf-custom-rule.png b/src/assets/images/learning-paths/mtls/configure-waf-custom-rule.png new file mode 100644 index 00000000000000..d7e293651f6195 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/configure-waf-custom-rule.png differ diff --git a/src/assets/images/learning-paths/mtls/expose-mtls-workers.png b/src/assets/images/learning-paths/mtls/expose-mtls-workers.png new file mode 100644 index 00000000000000..26fd84007d0db3 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/expose-mtls-workers.png differ diff --git a/src/assets/images/learning-paths/mtls/rate-limiting-rule.png b/src/assets/images/learning-paths/mtls/rate-limiting-rule.png new file mode 100644 index 00000000000000..f0e2b879f42239 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/rate-limiting-rule.png differ diff --git a/src/assets/images/learning-paths/mtls/waf-client-certificates-fingerprint.png b/src/assets/images/learning-paths/mtls/waf-client-certificates-fingerprint.png new file mode 100644 index 00000000000000..ba65167368fcd6 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/waf-client-certificates-fingerprint.png differ diff --git a/src/assets/images/learning-paths/mtls/waf-custom-rule-action-block.png b/src/assets/images/learning-paths/mtls/waf-custom-rule-action-block.png new file mode 100644 index 00000000000000..829fa150b53622 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/waf-custom-rule-action-block.png differ diff --git a/src/assets/images/learning-paths/mtls/waf-custom-rule.png b/src/assets/images/learning-paths/mtls/waf-custom-rule.png new file mode 100644 index 00000000000000..f4f1e616adbe79 Binary files /dev/null and b/src/assets/images/learning-paths/mtls/waf-custom-rule.png differ diff --git a/src/content/docs/learning-paths/mtls/concepts/benefits.mdx b/src/content/docs/learning-paths/mtls/concepts/benefits.mdx new file mode 100644 index 00000000000000..254f5293c8ce5d --- /dev/null +++ b/src/content/docs/learning-paths/mtls/concepts/benefits.mdx @@ -0,0 +1,14 @@ +--- +title: Benefits of mTLS +pcx_content_type: overview +sidebar: + order: 2 +--- + +- **Stronger authentication**: mTLS ensures mutual verification between the client and server, confirming that both parties are who they claim to be. This two-way authentication mechanism prevents impersonation and man-in-the-middle attacks, significantly enhancing the overall security. + +- **End-to-end encryption**: All communication between the client and server is encrypted, providing robust protection against eavesdropping and interception. Even if the data is captured by unauthorized parties, it remains secure and unreadable due to encryption. + +- **Preserved data integrity**: mTLS ensures that data remains unaltered during transit. The protocol verifies the integrity of transmitted information, protecting it from tampering or manipulation by malicious actors, ensuring the data's authenticity. + +- **Defense against insider threats**: mTLS strengthens internal network security by adding protection against insider threats. Unlike traditional "castle-and-moat" networking, which trusts anything inside the perimeter, mTLS enforces mutual authentication, ensuring all internal communications are verified and secure. diff --git a/src/content/docs/learning-paths/mtls/concepts/index.mdx b/src/content/docs/learning-paths/mtls/concepts/index.mdx new file mode 100644 index 00000000000000..a41bec30a1f882 --- /dev/null +++ b/src/content/docs/learning-paths/mtls/concepts/index.mdx @@ -0,0 +1,13 @@ +--- +title: Introducing mTLS +pcx_content_type: overview +sidebar: + label: Introducing mTLS + 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. + +[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. + +Mutual TLS (mTLS) adds an extra layer by authenticating both parties involved in the communication. The client presents a certificate to the server (in this case Cloudflare) and vice versa. diff --git a/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx b/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx new file mode 100644 index 00000000000000..5486149bb97f0b --- /dev/null +++ b/src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx @@ -0,0 +1,22 @@ +--- +title: mTLS at Cloudflare +pcx_content_type: overview +sidebar: + order: 3 +--- + +In this implementation guide we will be focusing on the L7 / Application Layer security for HTTP/S requests targeting [proxied](/dns/manage-dns-records/reference/proxied-dns-records/) hostnames, including the [first connection](/ssl/origin-configuration/ssl-modes/) between client and Cloudflare. + +Some common mTLS use cases are: +- Protect and verify legitimate API traffic by verifying Client Certificates provided during TLS/SSL handshakes. +- Check IoT devices' identity by verifying Client Certificates they provide during TLS/SSL handshakes. + +There are two main ways to use mTLS at Cloudflare, either by using the Application Security offering (optionally including [API Shield](/api-shield/)) or [Cloudflare Access](/cloudflare-one/policies/access/). Below is a non-exhaustive overview table of their differences: + +| Feature | Application Security (Client Certificate \+ WAF) | Cloudflare Access (mTLS) | +| :---- | :---- | :---- | +| 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 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. | \ No newline at end of file diff --git a/src/content/docs/learning-paths/mtls/index.mdx b/src/content/docs/learning-paths/mtls/index.mdx new file mode 100644 index 00000000000000..67cadcd502d8cd --- /dev/null +++ b/src/content/docs/learning-paths/mtls/index.mdx @@ -0,0 +1,15 @@ +--- +title: mTLS at Cloudflare +type: developers-site +new_learning_path: true +pcx_content_type: learning-path +head: + - tag: title + content: mTLS at Cloudflare +description: Safeguarding APIs and devices on Cloudflare's network. + +--- + +import { LearningPath } from "~/components" + + 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 new file mode 100644 index 00000000000000..761449b363c284 --- /dev/null +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx @@ -0,0 +1,94 @@ +--- +title: mTLS with Application Security +pcx_content_type: overview +sidebar: + order: 1 +--- + +:::note +This implementation requires an active [Zone](/fundamentals/setup/accounts-and-zones/#zones), a valid [Edge Certificate](/ssl/edge-certificates/), and [proxied](/dns/manage-dns-records/reference/proxied-dns-records/) hostname.
+ +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. +::: + +## 1. Enable mTLS + +1. Go to your Cloudflare dashboard and select your account and domain. +2. Go to **SSL/TLS** > **[Client Certificates](/ssl/client-certificates/)** tab and select **Edit** to add the Hosts (hostnames) you want to [enable mTLS](/ssl/client-certificates/enable-mtls/) for. + + Example host: `mtls-test.example.com` + +3. Select **Create Certificate** and fill in the required fields. You can choose one of the following options: + +- Generate a private key (usually referred to as Private Certificate) and Certificate Signing Request (CSR) with Cloudflare (which includes the Public Certificate). +- Use your own private key and CSR which 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: + +```txt +openssl req -new -newkey rsa:2048 -nodes -keyout client1.key -out client1.csr -subj '/C=GB/ST=London/L=London/O=Organization/CN=CommonName' +``` + +Or use a script like this one from [GitHub](https://github.com/erfianugrah/rootcatest/blob/main/fullgenerator.py). + +Do not forget to copy the values shown when creating the certificate as they become unavailable after creation. + +## 2. Install the client certificate + +In order for a client to utilize the Client Certificate you created, it must be on the devices that you want to use them on. You will want to place them in the same directory as your process / script that targets your APIs / hostnames. + +We generally recommended using one Client Certificate per device. Configuring your system to actually use the Public and Private Certificates is especially important. + +An example is to [add both certificates to the Keychain](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac) on a MacBook laptop. + +Another example is to generate a [PKCS12 (P12) certificate](https://en.wikipedia.org/wiki/PKCS_12) file and then [add it to your browser](https://www.ibm.com/docs/en/engineering-lifecycle-management-suite/lifecycle-management/7.0.2?topic=dashboards-importing-certificates-configuring-browsers): + +```txt +openssl pkcs12 -export -out certificate.p12 -inkey private-cert.pem -in cert.pem +``` + +Use the values from the previous step. + +Example using cURL command: + +```cURL +curl -v --cert cert.pem --key private-cert.pem +``` + +Use the values from the previous step. + +## 3. Validate the client certificate in the WAF + +mTLS is verified and checked in the [Cloudflare WAF phase](/waf/reference/phases/). This is done by creating WAF [Custom Rules](/waf/custom-rules/) using the dynamic fields. + +All Client Certificate details can be found in the [`cf.tls_*`](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_cipher) dynamic fields in the [Cloudflare Ruleset Engine](/ruleset-engine/). + +Example WAF Custom Rule with action block: + +![Example of a WAF custom rule with an action block in the Cloudflare dashboard during the validate client certificate step](~/assets/images/learning-paths/mtls/waf-custom-rule-action-block.png) + +## Demo + +:::note +Ensure you are not using a VPN that could interfere with certificates or TLS decryption. If needed, enable [Split Tunnels](/cloudflare-one/connections/connect-devices/warp/configure-warp/route-traffic/split-tunnels/) for specific hostnames to bypass the VPN for trusted services, such as the mTLS hostnames. +::: + +With the Public and Private Certificates in the same directory, with this cURL command, we will gain access: + +```curl +curl -I --cert cert.pem --key private-cert.pem https://mtls-test.example.com/mtls-test + +HTTP/2 200 +server: cloudflare +``` + +Without the certificates, the terminal will display the following: + +```curl +$ curl -I https://mtls-test.example.com/mtls-test + +HTTP/2 403 +server: cloudflare +``` \ No newline at end of file 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 new file mode 100644 index 00000000000000..fb22c7a3f1f6e0 --- /dev/null +++ b/src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx @@ -0,0 +1,161 @@ +--- +title: mTLS related features +pcx_content_type: overview +sidebar: + order: 2 +--- + +## Label Client Certificates + +To make it easier to differentiate between Client Certificates, you can generate your own private key and CSR, and enter information that will be incorporated into your certificate request, essentially [labeling your Client Certificates](/ssl/client-certificates/label-client-certificate/). + +## Certificate Revocation + +In cases of noticing excessive traffic, anomalous traffic (strange sequences of requests), or generally too many attack attempts registered from specific devices using your Client Certificates, it is best to [revoke](/ssl/client-certificates/revoke-client-certificate/) those. + +Additionally, ensure to have a WAF [Custom Rule](/waf/custom-rules/) in place to block [revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates. Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_cipher) dynamic fields. + +Example WAF Custom Rule with action block: + +![Example expression for certification revocation using a WAF custom rule in the Cloudflare dashboard](~/assets/images/learning-paths/mtls/certification-revocation-custom-rule.png) + +```text +(cf.tls_client_auth.cert_revoked) +``` + +A better approach may be to check for unverified or revoked client certificates: + +```txt +(not cf.tls_client_auth.cert_verified) or cf.tls_client_auth.cert_revoked +``` + +Generally, ensure client certificates are rotated regularly and safely to reduce the risk of compromise. + +## 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. + +## Bring your own CA for mTLS + +If you already have mTLS implemented, client certificates are already installed on devices, and therefore you would like to use your own Certificate Authority (CA), this is possible by [bringing your own CA for mTLS](/ssl/client-certificates/byo-ca/). + +Here you can use the [Replace Hostname Associations API endpoint](/api/operations/client-certificate-for-a-zone-put-hostname-associations) to enable mTLS in each hostname that should use the CA for mTLS validation, essentially associating your CAs specific with hostnames. + +:::note +Each Enterprise account can upload up to five CAs, though this can be increased. Contact your account team if you require more. +::: + +## Client Certificate Deployment + +There are different ways to safely and securely deploy Client Certificates across devices. + +Some of the most used methods are [embedding](/ssl/client-certificates/configure-your-mobile-app-or-iot-device/#step-3--embed-the-client-certificate-in-your-mobile-app) the Client Certificate into an application and allowing user devices to download and install that app, or use mobile device management (MDM) to distribute certificates across devices, or to allow user devices to directly download and install the Client Certificate into a device's Certificate Store. + +Issuing a certificate is an important step, so if possible, perform thorough client verification. + +In complex microservices environments, you can leverage Service Mesh to automate and enforce mTLS at scale. For example, Cloudflare services can handle external traffic security, while Service Mesh technologies enforce mTLS for east-west traffic within your network. This ensures that external traffic is secured by Cloudflare, while internal microservice communication is protected using mTLS via the Service Mesh. + +## Customize Cipher Suites + +It is generally recommended to [customize the cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/customize-cipher-suites/) of your Cloudflare [Edge Certificates](/ssl/edge-certificates/). This only applies to the Edge Certificates, not Client Certificates. + +The recommended TLS versions for mTLS are: +- TLS 1.2: still broadly compatible and secure. +- TLS 1.3: preferred for new implementations due to its enhanced security and efficiency. + +Using outdated versions like TLS 1.0 or 1.1 is not recommended due to known vulnerabilities. + +:::note +For modern mTLS implementations, Elliptic Curve Cryptography (EC) and [modern cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites/) are recommended because it offers faster handshakes and better performance, uses smaller key sizes which result in reduced computational overhead while maintaining strong security, and EC is more scalable for large-scale deployments, such as in cloud-native applications, microservices, and mobile networks. RSA is only recommended if you have legacy systems that cannot support EC or if you require compatibility with systems that only work with RSA. +::: + +## TLS Session Resumption + +Browsers connecting to a domain with a [wildcard](/dns/manage-dns-records/reference/wildcard-dns-records/) [Edge Certificate](/ssl/edge-certificates/) in place, connecting to the same domain's mTLS subdomain could cause a non-authentication event, due to TLS Session Resumption, or also called [Connection Resumption](/speed/optimization/protocol/0-rtt-connection-resumption/). + +It is generally not recommended to use wildcard certificates. + +Review the [troubleshooting documentation](/ssl/client-certificates/troubleshooting/) for more info. + +## TLS Session Renegotiation + +:::note +Resumption and renegotiation are essentially opposites. Resumption re-establishes a previous TLS session over a new TCP connection, keeping the same TLS parameters. In contrast, renegotiation updates certain TLS parameters within an existing session, continuing over the same TCP connection. +::: + +If you need to use Client Certificates after the TLS handshake via renegotiation, you will need to use a prior TLS version than 1.3. This is because TLS 1.3 does not support renegotiation. + +For example, if you are using mTLS and you are restricting requests to certain folders, based on a URL path in the request, rather than all content on your origin server, a TLS renegotiation may be triggered. Connections using TLS 1.3 do not support renegotiation. + +## Chain of Trust + +Customers create Client Certificates and select the option to _use my private key and CSR_. The customer provides the CSR supplied by end-customers to generate the client certificates shared with end-customers. However, if your end-customers request the Certificate Chain, this can potentially be shared by the Cloudflare account team. + +Contact your account team for more information. + +## WAF for Client Certificates + +:::note +[Revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates are not automatically blocked unless you have an active WAF Custom Rule specifically checking for and blocking them. This check only applies to Client Certificates issued by the Cloudflare-managed CA. Cloudflare currently does not check certificate revocation lists (CRL) for CAs that have been uploaded by the customer ([BYO CA](/ssl/client-certificates/byo-ca/)). One can opt for Workers to manage a custom business logic and block revoked Client Certificates. See the [Workers section](/learning-paths/mtls/mtls-workers/) for more information. +::: + +In order to effectively implement mTLS with Cloudflare, it is strongly recommended to properly configure the [Cloudflare WAF](/waf/). Review the available [`cf.tls_*`](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_cipher) dynamic fields. + +Example WAF Custom Rule with action block: + +![Example expression for configure a WAF Custom Rule with action block ](~/assets/images/learning-paths/mtls/configure-waf-custom-rule.png) + +```txt +(http.host in {"mtls.example.com" "mtls2.example.com"} and (not cf.tls_client_auth.cert_verified or cf.tls_client_auth.cert_revoked)) +``` + +This expression will check if the request is coming from one of the hostnames and will block the request if the Client Certificate is either not verified or revoked. + +Another example WAF Custom Rule with action block, using the [cf.tls_client_auth.cert_fingerprint_sha256](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_client_authcert_fingerprint_sha256) field, for a specific Client Certificate (replace `ADD_STRING_OF_CLIENT_CERT_SHA256_FINGERPRINT`): + +![Example expression of a WAF Custom Rule with action block using the cf.tls_client_auth.cert_fingerprint_sha256 field](~/assets/images/learning-paths/mtls/waf-client-certificates-fingerprint.png) + +```txt +(http.request.uri.path in {"/headers"} and http.host in {"mtls.example.com" "mtls2.example.com"} and not cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 ne "ADD_STRING_OF_CLIENT_CERT_SHA256_FINGERPRINT") +``` + +Here is another example of a WAF custom rule to associate a serial number with a hostname: + +![Example expression of a WAF Custom Rule to associate a serial number with a hostname](~/assets/images/learning-paths/mtls/waf-custom-rule.png) + +```txt +(http.host in {"mtls.example.com" "mtls2.example.com"} and cf.tls_client_auth.cert_serial ne "ADD_STRING_OF_CLIENT_CERT_SERIAL") +``` + +This expression will check for a specific [Client Certificate serial number](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_client_authcert_serial) linked to specific hostnames, allowing for more granular control. + +## 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: +- `Cf-Client-Cert-Der-Base64` (raw certificate in DER format, encoded as base64) +- `Cf-Client-Cert-Sha256` (SHA256 fingerprint of the certificate) + +The header `Cf-Client-Cert-Sha256` can be used within the [Rate Limiting characteristics](/waf/rate-limiting-rules/parameters/#with-the-same-characteristics) "Header value of". + +Example [Rate Limiting Rule](/waf/rate-limiting-rules/): + +![Example exmpression of a rate limiting rule from the Cloudflare dashboard](~/assets/images/learning-paths/mtls/rate-limiting-rule.png) + +```txt +(http.host in {"mtls.example.com" "mtls2.example.com"} and cf.tls_client_auth.cert_verified) + +With the same characteristics... +"Header value of": "Cf-Client-Cert-Sha256" +``` + +## Cloudflare API Shield + +In addition to mTLS, customers can purchase [API Shield](/api-shield/) features, such as API Discovery, API Routing, Volumetric Abuse Detection, Sequence Mitigation, JWT Validation, Schema Validation, and more. + +## Cloudflare Workers + +Cloudflare Workers can provide details around the Client Certificate, such as returning information via headers to the client or to the origin server. Learn more in the [mTLS with Workers section](/learning-paths/mtls/mtls-workers/) below. + + +:::note +Snippets do not support any [Bindings](/workers/runtime-apis/bindings/) and do not work with mTLS. However, you can [validate JSON web tokens (JWT)](/rules/snippets/examples/jwt-validation/). \ No newline at end of file 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 new file mode 100644 index 00000000000000..27f77b9a3a54c4 --- /dev/null +++ b/src/content/docs/learning-paths/mtls/mtls-cloudflare-access/index.mdx @@ -0,0 +1,141 @@ +--- +title: mTLS with Cloudflare Access +pcx_content_type: overview +sidebar: + order: 2 +--- + +:::note +This requires an active Enterprise [Account](/fundamentals/setup/accounts-and-zones/#accounts) with Cloudflare Access enabled. +::: + +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 integrate with a Zero Trust solution. + +## 1. Create a CA + +The CA certificate can be from a publicly trusted CA or self-signed. + +In case you want to [create your own CA](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#test-mtls-using-cloudflare-pki) from scratch, you can follow these example steps and adapt the information to your own needs: + +1. Create a JSON file called `ca-csr.json`: + +```json +{ + "CN": "Cloudflare Access Testing CA", + "key": { + "algo": "rsa", + "size": 4096 + }, + "names": [ + { + "C": "US", + "L": "LA", + "O": "Access Testing", + "OU": "CA", + "ST": "California" + } + ] + } +``` + +2. Create a JSON file called `ca-config.json`: + +```json +{ + "signing": { + "default": { + "expiry": "8760h" + }, + "profiles": { + "server": { + "usages": ["signing", "key encipherment", "server auth"], + "expiry": "8760h" + }, + "client": { + "usages": ["signing","key encipherment","client auth"], + "expiry": "8760h" + } + } + } +} +``` + +3. Run the following [cfssl](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#test-mtls-using-cloudflare-pki) command to generate the CA certificate `ca.pem`: + +```txt +cfssl gencert -initca ca-csr.json | cfssljson -bare ca +``` + +## 2. Create Client Certificates + +1. In order to create the Client Certificates, you need to prepare the following JSON file called `client-csr.json`: + +```json +{ + "CN": "mtls-access.example.com", # replace with your own hostname + "hosts": ["mtls-access.example.com"], # replace with your own hostname + "key": { + "algo": "rsa", + "size": 4096 + }, + "names": [ + { + "C": "US", + "L": "Austin", + "O": "Access", + "OU": "Access Admins", + "ST": "Texas" + } + ] + } + ``` + +2. Now you can run the following command to generate the Client Certificates, which will output the files `client.pem`, `client-key.pem` and `client.csr`: + +```txt +cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=client client-csr.json | cfssljson -bare client +``` + +## 3. Add mTLS CA certificate to Cloudflare Access + +Follow the steps outlined in the [developer documentation](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#add-mtls-authentication-to-your-access-configuration). + +Using the example from Step 2: upload the `ca.pem` to your Cloudflare Access account via the [dashboard](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#add-mtls-authentication-to-your-access-configuration) or [Cloudflare API](/api/operations/access-mtls-authentication-add-an-mtls-certificate). + +Do not forget to enter the fully-qualified domain names (FQDN / associated hostnames) that will use this CA certificate. + +Customers can identify which client sends the Client Certificates by [forwarding client certificate headers](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#forward-a-client-certificate) to the origin server. Customers can then store and use the certificate information such as Common Name (CN), Serial number, and other fields along with the device number to perform additional checks or logics. + +Additionally, authenticated requests also send the `Cf-Access-Jwt-Assertion\` JWT header to the origin server. To decode the header value, you can use [jwt.io](https://jwt.io/). + +## 4. Create the self-hosted applications + +Finally, the hostname you want to protect with mTLS needs to be added as a [self-hosted app](/cloudflare-one/applications/configure-apps/self-hosted-apps/) in Cloudflare Access, defining an [Access Policy](/cloudflare-one/policies/access/) which uses the action [Service Auth](/cloudflare-one/policies/access/#service-auth) and the Selector *“Valid Certificate”*, or simply requiring an [IdP](/cloudflare-one/identity/idp-integration/) authentication. You can also take advantage of extra requirements, such as the “Common Name” (CN), which expects the indicated hostname, and more [Selectors](/cloudflare-one/policies/access/#selectors). Alternatively, one can also [extend ZTNA with external authorization and serverless computing](/reference-architecture/diagrams/sase/augment-access-with-serverless/). + +## Demo + +:::note +Make sure that you are not using any VPN that could interfere with the certificates or TLS decryption. +::: + +With the Public and Private Client Certificates in the same directory, with this cURL command, we will gain access: + +```curl +curl -IXGET --cert client.pem --key client-key.pem https://mtls-access.example.com/ + +HTTP/2 200 +server: cloudflare +``` + +Without the certificates, we'd see the following: + +```curl +curl -I https://mtls-access.example.com/mtls-test + +HTTP/2 401 +server: cloudflare +``` \ No newline at end of file diff --git a/src/content/docs/learning-paths/mtls/mtls-implementation/index.mdx b/src/content/docs/learning-paths/mtls/mtls-implementation/index.mdx new file mode 100644 index 00000000000000..4c432eda5ec929 --- /dev/null +++ b/src/content/docs/learning-paths/mtls/mtls-implementation/index.mdx @@ -0,0 +1,24 @@ +--- +title: Types of mTLS implementation +pcx_content_type: overview +sidebar: + order: 3 +--- + +There are different ways to implement mTLS authentication. The most common ones are: + +## Option 1: mTLS Device Authentication + +This version of mTLS is for device certificates, primarily focused on the number of IoT devices, not user devices. + +Here we recommend using [mTLS with Application Security](/learning-paths/mtls/mtls-app-security/). + +## Option 2: mTLS User Authentication + +When a user wants to establish a secure connection with a server, they present their certificate to the server, which verifies its authenticity. Once the certificate is authenticated, an encrypted connection is established between the user and the server, and all data transmitted between them is encrypted to protect against interception by third parties. + +mTLS user authentication is included with Cloudflare Access and depends on the number of users. + +## Option 3: mTLS Service Authentication + +The hostnames are used to look up the certificates and verify their authenticity. Once the connection is established, all data transmitted between the hosts is encrypted, ensuring that it cannot be intercepted and read by third parties. Here the main driver is the number of hostnames. \ No newline at end of file diff --git a/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx b/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx new file mode 100644 index 00000000000000..9039ed9908a28b --- /dev/null +++ b/src/content/docs/learning-paths/mtls/mtls-workers/index.mdx @@ -0,0 +1,67 @@ +--- +title: mTLS with Workers +pcx_content_type: overview +sidebar: + order: 4 +--- + +:::note +Cloudflare Workers runs after the Cloudflare WAF and Cloudflare Access. Review the [Traffic Sequence](https://blog.cloudflare.com/traffic-sequence-which-product-runs-first/) visible on the Cloudflare dashboard. +::: + +[mTLS for Workers](/workers/runtime-apis/bindings/mtls/) can be used for requests made to services that are [not proxied](/dns/manage-dns-records/reference/proxied-dns-records/#dns-only-records) on Cloudflare, or alternatively used to gain visibility into certificate details and optionally add your own programmatic logic for further checks or actions. + +## Expose mTLS headers + +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): + +```js +addEventListener('fetch', event => { + event.respondWith( + (async request => { + const { tlsClientAuth = {} } = request.cf || {}; + const tlsHeaders = { + 'X-CERT-ISSUER-DN': tlsClientAuth.certIssuerDN, + 'X-CERT-SUBJECT-DN': tlsClientAuth.certSubjectDN, + 'X-CERT-ISSUER-DN-L': tlsClientAuth.certIssuerDNLegacy, + 'X-CERT-SUBJECT-DN-L': tlsClientAuth.certSubjectDNLegacy, + 'X-CERT-SERIAL': tlsClientAuth.certSerial, + 'X-CERT-FINGER': tlsClientAuth.certFingerprintSHA1, + 'X-CERT-VERIFY': tlsClientAuth.certVerify, + 'X-CERT-NOTBE': tlsClientAuth.certNotBefore, + 'X-CERT-NOTAF': tlsClientAuth.certNotAfter + }; + + const headers = Object.fromEntries(request.headers); + return new Response(JSON.stringify({ ...headers, ...tlsHeaders }, null, 2), { + headers: { 'Content-Type': 'application/json' } + }); + })(event.request) + ); +}); +``` + +The response when using the browser with a P12 Certificate to visit the mTLS hostname would look similar to this example: + +![Example response after exposing an mTLS header with Cloudflare Workers](~/assets/images/learning-paths/mtls/expose-mtls-workers.png) + +```txt +{ + "X-CERT-ISSUER-DN": "CN=Managed CA abcdefghijklmnopq123456789,OU=www.cloudflare.com,O=Cloudflare\\, Inc.,L=San Francisco,ST=California,C=US", + "X-CERT-SUBJECT-DN": "CN=Cloudflare,C=US", + "X-CERT-ISSUER-DN-L": "/C=US/ST=California/L=San Francisco/O=Cloudflare, Inc./OU=www.cloudflare.com/CN=Managed CA abcdefghijklmnopq123456789", + "X-CERT-SUBJECT-DN-L": "/C=US/CN=Cloudflare", + "X-CERT-SERIAL": "37C52778E2F1820CC6342172A0E0ED33A4555F8B", + "X-CERT-FINGER": "161e3a2089add0b2134ec43c9071f460e9f4b898", + "X-CERT-NOTBE": "May 25 23:11:00 2024 GMT", + "X-CERT-NOTAF": "May 23 23:11:00 2034 GMT" +} +``` + +:::note +The client certificate serial number is a unique identifier assigned to each certificate by the CA, ensuring that no two certificates issued by the same CA have the same serial number. This can be useful to track and monitor certificate usage or abuse. +::: + +This approach can also be useful to handle additional checks and logic on the mTLS via the Cloudflare Workers. diff --git a/src/content/learning-paths/mtls.json b/src/content/learning-paths/mtls.json new file mode 100644 index 00000000000000..6506560485256d --- /dev/null +++ b/src/content/learning-paths/mtls.json @@ -0,0 +1,9 @@ +{ + "title": "mTLS at Cloudflare", + "path": "/learning-paths/mtls/", + "priority": 5, + "description": "Safeguard APIs and Devices on Cloudflare's network.", + "products": ["API Shield", "Access", "SSL/TLS"], + "product_group": "Cloudflare One", + "additional_groups": ["Application security"] +}