Skip to content

Commit 8c2e389

Browse files
[CF1] improve manual certificate deployment documentation
1 parent 6dd7a72 commit 8c2e389

File tree

1 file changed

+27
-7
lines changed

1 file changed

+27
-7
lines changed

src/content/docs/cloudflare-one/team-and-resources/devices/user-side-certificates/manual-deployment.mdx

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: Manually add a Cloudflare certificate to mobile devices and
1010

1111
import { Details, Render, TabItem, Tabs } from "~/components";
1212

13+
If desktop, go to WARP page. If mobile, keep reading.
14+
1315
:::note
1416
This procedure is only required to enable specific Cloudflare Zero Trust features, and should only be done at the direction of your IT department. This procedure is not required to enable the WARP client for consumers.
1517
:::
@@ -18,7 +20,13 @@ If your device does not support [certificate installation via WARP](/cloudflare-
1820

1921
Zero Trust will only inspect traffic using installed certificates set to [**Available** and **In-Use**](/cloudflare-one/team-and-resources/devices/user-side-certificates/#activate-a-root-certificate).
2022

21-
## Download the Cloudflare root certificate
23+
By following this guide, you will:
24+
25+
1. Download a Cloudflare certificate and verify it.
26+
2. Install the certificate in your operating system's certificate store.
27+
3. If a target application does not accept certificates from the operating system, you must install the certificate in the application's certificate store.
28+
29+
## 1. Download and verify the Cloudflare root certificate
2230

2331
:::note[Download limitation]
2432
You can only download Cloudflare-generated certificates from the Zero Trust dashboard or with WARP.
@@ -35,11 +43,11 @@ First, [generate](/cloudflare-one/team-and-resources/devices/user-side-certifica
3543

3644
Alternatively, you can download and install a certificate [using WARP](/cloudflare-one/team-and-resources/devices/user-side-certificates/automated-deployment/#install-a-certificate-using-warp). WARP will add the certificates to the device's system certificate store in `installed_certs/<certificate_id>.pem`.
3745

38-
### Verify the downloaded certificate
46+
## 2. Verify the downloaded certificate
3947

4048
To verify your download, use a terminal to check that the downloaded certificate's hash matches the thumbprint listed under **Certificate thumbprint**. For example:
4149

42-
#### SHA1
50+
### SHA1
4351

4452
```sh title="SHA1 .crt example"
4553
openssl x509 -noout -fingerprint -sha1 -inform der -in <certificate.crt>
@@ -57,7 +65,7 @@ openssl x509 -noout -fingerprint -sha1 -inform pem -in <certificate.pem>
5765
SHA1 Fingerprint=BB:2D:B6:3D:6B:DE:DA:06:4E:CA:CB:40:F6:F2:61:40:B7:10:F0:6C
5866
```
5967

60-
#### SHA256
68+
### SHA256
6169

6270
```sh title="SHA256 .crt example"
6371
openssl x509 -noout -fingerprint -sha256 -inform der -in <certificate.crt>
@@ -75,7 +83,9 @@ openssl x509 -noout -fingerprint -sha256 -inform pem -in <certificate.pem>
7583
sha256 Fingerprint=F5:E1:56:C4:89:78:77:AD:79:3A:1E:83:FA:77:83:F1:9C:B0:C6:1B:58:2C:2F:50:11:B3:37:72:7C:62:3D:EF
7684
```
7785

78-
### Convert the certificate
86+
## 3. (Optional) Convert the certificate
87+
88+
Depending on your operating system, you may need to convert the certificate to a different file type.
7989

8090
Some applications require a certificate formatted in the `.cer` file type. You can convert your downloaded certificate using [OpenSSL](https://www.openssl.org/):
8191

@@ -105,6 +115,10 @@ Some applications require a certificate formatted in the `.cer` file type. You c
105115

106116
## Add the certificate to operating systems
107117

118+
If you are deploying the Cloudflare certificate to desktop devices, use the [Install certificate using WARP](/cloudflare-one/team-and-resources/devices/user-side-certificates/automated-deployment/) method.
119+
120+
Mobile devices require manual installations detailed in the instructions below.
121+
108122
### macOS
109123

110124
In macOS, you can choose the keychain in which you want to install the certificate. Each keychain impacts which users will be affected by trusting the root certificate.
@@ -298,14 +312,20 @@ After adding the Cloudflare certificate to ChromeOS, you may also have to [insta
298312

299313
## Add the certificate to applications
300314

301-
Some packages, development tools, and other applications provide options to trust root certificates that will allow for the traffic inspection features of Gateway to work without breaking the application.
315+
Some applications do not use the system certificate store and therefore require the certificate to be added to the application directly. For certain applications like the ones below, you will need to follow the steps in this section and add the Cloudflare certificate to the application for TLS decryption to function properly.
316+
317+
If you do not update the application to trust the Cloudflare certificate, the application will refuse to connect and you will receive an untrusted certificate error.
302318

303-
All of the applications below first require downloading a Cloudflare certificate with the instructions above. On macOS, the default path to the system keychain database file is `/Library/Keychains/System.keychain`. On Windows, the default path is `\Cert:\CurrentUser\Root`.
319+
All of the applications below first require downloading a Cloudflare certificate with [the instructions above](#download-the-cloudflare-root-certificate). On macOS, the default path to the system keychain database file is `/Library/Keychains/System.keychain`. On Windows, the default path is `\Cert:\CurrentUser\Root`.
304320

305321
:::note
306322
Some applications require the use of a publicly trusted certificate — they do not trust the system certificate, nor do they have a configurable private store. For these applications to function, you must add a [Do Not Inspect policy](/cloudflare-one/traffic-policies/http-policies/#do-not-inspect) for the domains or IPs that the application relies on.
307323
:::
308324

325+
:::caution
326+
Even if you deployed WARP through the [Install certificate using WARP](/cloudflare-one/team-and-resources/devices/user-side-certificates/automated-deployment/) method, you may still need to add the Cloudflare certificate to certain applications. The Install certificate using WARP method only installs the Cloudflare certificate to the operating system certificate store.
327+
:::
328+
309329
### Browsers
310330

311331
#### Chrome

0 commit comments

Comments
 (0)