Skip to content

Commit 876e546

Browse files
maxvpranbel
maxvp
and
ranbel
authored
[ZT] Update custom cert API calls (#19703)
Co-authored-by: ranbel <[email protected]>
1 parent 203a984 commit 876e546

File tree

3 files changed

+108
-99
lines changed

3 files changed

+108
-99
lines changed

‎src/content/docs/cloudflare-one/connections/connect-devices/user-side-certificates/custom-certificate.mdx‎

Lines changed: 96 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -65,94 +65,105 @@ openssl x509 -in <CUSTOM-ROOT-CERT>.pem -text
6565

6666
<Tabs syncKey="dashPlusAPI">
6767

68-
<TabItem label="Dashboard">
69-
1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Resources**.
70-
2. In **Certificates**, select **Manage**.
71-
3. Select **Upload certificate**.
72-
4. Enter the private key and SSL certificate you generated or select **Paste certificate from file** to upload them from a file.
73-
5. Select **Generate certificate**.
68+
<TabItem label="Dashboard">
69+
1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Resources**.
70+
2. In **Certificates**, select **Manage**.
71+
3. Select **Upload certificate**.
72+
4. Enter the private key and SSL certificate you generated or select **Paste certificate from file** to upload them from a file.
73+
5. Select **Generate certificate**.
7474

7575
You can now [use the generated custom root certificate](#use-a-custom-root-certificate) for inspection.
7676

77-
</TabItem>
78-
79-
<TabItem label="API">
80-
1. Verify that the certificate is installed on your devices.
81-
2. <Render file="upload-mtls-cert" params={{ one: " " }} />
82-
3. Deploy the certificate in Gateway using the certificate's UUID with the [Patch Zero Trust account configuration endpoint](/api/resources/zero_trust/subresources/gateway/subresources/configurations/methods/edit/).
83-
```bash {10}
84-
curl --request PATCH \
85-
"https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/configuration" \
86-
--header "X-Auth-Email: <EMAIL>" \
87-
--header "X-Auth-Key: <API_KEY>" \
88-
--header "Content-Type: application/json" \
89-
--data '{
90-
"settings": {
91-
"custom_certificate": {
92-
"enabled": true,
93-
"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60"
94-
}
95-
}
96-
}'
97-
```
98-
The response will return the pending status of the certificate. For example:
99-
```json {13}
100-
{
101-
"success": true,
102-
"errors": [],
103-
"messages": [],
104-
"result": {
105-
"settings": {
106-
"antivirus": {},
107-
"block_page": {},
108-
"custom_certificate":
109-
{
110-
"enabled": true,
111-
"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
112-
"binding_status": "pending_deployment",
113-
"qs_pack_id": "50a78g31-a5b5-4k58d-a6ed-b0ac17da9k05"
114-
},
115-
"tls_decrypt": {},
116-
"activity_log": {},
117-
"browser_isolation": {},
118-
"fips": {},
119-
},
120-
},
121-
"created_at": "2014-01-01T05:20:00.12345Z",
122-
"updated_at": "2014-01-01T05:20:00.12345Z"
123-
}
124-
```
125-
4. Activate the certificate for use in inspection with the [Activate a Zero Trust certificate endpoint](/api/resources/zero_trust/subresources/gateway/subresources/certificates/methods/activate/).
126-
```bash
127-
curl --request POST \
128-
"https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/certificates/{certificate_id}/activate" \
129-
--header "X-Auth-Email: <EMAIL>" \
130-
--header "X-Auth-Key: <API_KEY>"
131-
```
132-
The response will return the certificate and its current deployment status. For example:
133-
```json {6,12}
134-
{
135-
"errors": [],
136-
"messages": [],
137-
"success": true,
138-
"result": {
139-
"binding_status": "active",
140-
"certificate": "-----BEGIN CERTIFICATE-----\\nMIIDmDCCAoCgAwIBAgIUKTOAZNjcXVZRj4oQt0SHsl1c1vMwDQYJKoZIhvcNAQELBQAwUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgMDVNhbiBGcmFuY2lzY28xEzARBgNVBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4YW1wbGUgSW5jLjAgFw0yMjExMjIxNjU5NDdaGA8yMTIyMTAyOTE2NTk0N1owUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgMDVNhbiBGcmFuY2lzY28xEzARBgNVBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4YW1wbGUgSW5jLjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMRcORwgJFTdcG/2GKI+cFYiOBNDKjCZUXEOvXWY42BkH9wxiMT869CO+enA1w5pIrXow6kCM1sQspHHaVmJUlotEMJxyoLFfA/8Kt1EKFyobOjuZs2SwyVyJ2sStvQuUQEosULZCNGZEqoH5g6zhMPxaxm7ZLrrsDZ9maNGVqo7EWLWHrZ57Q/5MtTrbxQL+eXjUmJ9K3kS+3uEwMdqR6Z3BluU1ivanpPc1CN2GNhdO0/hSY4YkGEnuLsqJyDd3cIiB1MxuCBJ4ZaqOd2viV1WcP3oU3dxVPm4MWyfYIldMWB14FahScxLhWdRnM9YZ/i9IFcLypXsuz7DjrJPtPUCAwEAAaNmMGQwHQYDVR0OBBYEFP5JzLUawNF+c3AXsYTEWHh7z2czMB8GA1UdIwQYMBaAFP5JzLUawNF+c3AXsYTEWHh7z2czMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEBMA0GCSqGSIb3DQEBCwUAA4IBAQBc+Be7NDhpE09y7hLPZGRPl1cSKBw4RI0XIv6rlbSTFs5EebpTGjhx/whNxwEZhB9HZ7111Oa1YlT8xkI9DshB78mjAHCKBAJ76moK8tkG0aqdYpJ4ZcJTVBB7l98Rvgc7zfTii7WemTy72deBbSeiEtXavm4EF0mWjHhQ5Nxpnp00Bqn5g1x8CyTDypgmugnep+xG+iFzNmTdsz7WI9T/7kDMXqB7M/FPWBORyS98OJqNDswCLF8bIZYwUBEe+bRHFomoShMzaC3tvim7WCb16noDkSTMlfKO4pnvKhpcVdSgwcruATV7y+W+Lvmz2OT/Gui4JhqeoTewsxndhDDE\\n-----END CERTIFICATE-----\\n",
141-
"created_at": "2014-01-01T05:20:00.12345Z",
142-
"expires_on": "2014-01-01T05:20:00.12345Z",
143-
"fingerprint": "E9:19:49:AA:DD:D8:1E:C1:20:2A:D8:22:BF:A5:F8:FC:1A:F7:10:9F:C7:5B:69:AB:0:31:91:8B:61:B4:BF:1C",
144-
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
145-
"in_use": true,
146-
"issuer_org": "Example Inc.",
147-
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
148-
"type": "gateway_managed",
149-
"updated_at": "2014-01-01T05:20:00.12345Z",
150-
"uploaded_on": "2014-01-01T05:20:00.12345Z"
151-
}
152-
}
153-
```
154-
Once `binding_status` changes to `active`, Gateway will sign your traffic using the custom root certificate and private key. If you disable the custom certificate, Gateway will revert to the default Cloudflare certificate generated for your Zero Trust account.
155-
</TabItem>
77+
</TabItem>
78+
79+
<TabItem label="API">
80+
81+
1. <Render file="upload-mtls-cert" params={{ one: " " }} />
82+
83+
2. Set the certificate as available for use in inspection with the [Activate a Zero Trust certificate endpoint](/api/resources/zero_trust/subresources/gateway/subresources/certificates/methods/activate/). This will deploy the certificate across the Cloudflare global network.
84+
85+
```sh
86+
curl --request POST \
87+
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates/$CERTIFICATE_ID/activate" \
88+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
89+
```
90+
91+
The response will return the certificate and a `pending_deployment` binding status. For example:
92+
93+
```json {12}
94+
{
95+
"errors": [],
96+
"messages": [],
97+
"success": true,
98+
"result": {
99+
"in_use": false,
100+
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
101+
"certificate": "-----BEGIN CERTIFICATE-----\\n ... \\n-----END CERTIFICATE-----\\n",
102+
"issuer_org": "Example Inc.",
103+
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
104+
"fingerprint": "E9:19:49:AA:DD:D8:1E:C1:20:2A:D8:22:BF:A5:F8:FC:1A:F7:10:9F:C7:5B:69:AB:0:31:91:8B:61:B4:BF:1C",
105+
"binding_status": "pending_deployment",
106+
"type": "custom",
107+
"updated_at": "2014-01-01T05:20:00.12345Z",
108+
"uploaded_on": "2014-01-01T05:20:00.12345Z",
109+
"created_at": "2014-01-01T05:20:00.12345Z",
110+
"expires_on": "2014-01-01T05:20:00.12345Z"
111+
}
112+
}
113+
```
114+
115+
3. Use the [Get Zero Trust certificate details endpoint](/api/resources/zero_trust/subresources/gateway/subresources/certificates/methods/get/) to verify the certificate's binding status is set to `available`.
116+
117+
```sh
118+
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates/$CERTIFICATE_ID \
119+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
120+
```
121+
122+
```json {12}
123+
{
124+
"errors": [],
125+
"messages": [],
126+
"success": true,
127+
"result": {
128+
"in_use": false,
129+
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
130+
"certificate": "-----BEGIN CERTIFICATE-----\\n ... \\n-----END CERTIFICATE-----\\n",
131+
"issuer_org": "Example Inc.",
132+
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
133+
"fingerprint": "E9:19:49:AA:DD:D8:1E:C1:20:2A:D8:22:BF:A5:F8:FC:1A:F7:10:9F:C7:5B:69:AB:0:31:91:8B:61:B4:BF:1C",
134+
"binding_status": "available",
135+
"type": "custom",
136+
"updated_at": "2014-01-01T05:20:00.12345Z",
137+
"uploaded_on": "2014-01-01T05:20:00.12345Z",
138+
"created_at": "2014-01-01T05:20:00.12345Z",
139+
"expires_on": "2014-01-01T05:20:00.12345Z"
140+
}
141+
}
142+
```
143+
144+
4. (Optional) Verify the certificate is installed on your user's devices either [with WARP](/cloudflare-one/connections/connect-devices/user-side-certificates/automated-deployment/) or [manually](/cloudflare-one/connections/connect-devices/user-side-certificates/manual-deployment/).
145+
146+
5. Use the [Patch Zero Trust account configuration endpoint](/api/resources/zero_trust/subresources/gateway/subresources/configurations/methods/edit/) to turn on the certificate for use in inspection. For example:
147+
148+
```sh {9}
149+
curl --request PATCH \
150+
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/configuration" \
151+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
152+
--header "Content-Type: application/json" \
153+
--data '{
154+
"settings": {
155+
"certificate": {
156+
"id": "$CERTIFICATE_ID",
157+
"in_use": true
158+
}
159+
}
160+
}'
161+
```
162+
163+
Once `in-use` is set to `true`, Gateway will sign your traffic using the custom root certificate and private key. If you turn off or deactivate the custom certificate, Gateway will revert to the next available Cloudflare certificate generated for your Zero Trust account.
164+
165+
</TabItem>
166+
156167
</Tabs>
157168

158169
:::caution[Private key visibility]

‎src/content/docs/cloudflare-one/connections/connect-devices/user-side-certificates/index.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ Send a `POST` request to the [Create Zero Trust certificate](/api/resources/zero
5050

5151
```sh
5252
curl --request POST \
53-
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/certificates \
54-
--header "Authorization: Bearer <API_TOKEN>"
53+
https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates \
54+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
5555
```
5656

5757
The API will respond with the ID and contents of the new certificate.
@@ -87,8 +87,8 @@ Send a `POST` request to the [Activate a Zero Trust certificate](/api/resources/
8787

8888
```sh
8989
curl --request POST \
90-
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/certificates/{certificate_id}/activate \
91-
--header "Authorization: Bearer <API_TOKEN>"
90+
https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates/$CERTIFICATE_ID/activate \
91+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
9292
```
9393

9494
</TabItem> </Tabs>
@@ -112,13 +112,13 @@ Send a `PUT` request to the [Update Zero Trust account configuration](/api/resou
112112

113113
```sh
114114
curl --request PUT \
115-
'https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/configuration' \
115+
'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/configuration' \
116+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
116117
--header "Content-Type: application/json" \
117-
--header "Authorization: Bearer <API_TOKEN>" \
118118
--data '{
119119
"settings": {
120120
"certificate": {
121-
"id": "<CERTIFICATE_ID>",
121+
"id": "$CERTIFICATE_ID",
122122
"in_use": true
123123
}
124124
}

‎src/content/partials/cloudflare-one/upload-mtls-cert.mdx‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
---
22
inputParameters: param1
3-
43
---
54

6-
import { Markdown } from "~/components"
5+
import { Markdown } from "~/components";
76

87
Use the [Upload mTLS certificate endpoint](/api/resources/mtls_certificates/methods/create/) to upload the certificate and private key to Cloudflare. The certificate must be a root CA, formatted as a single string with `\n` replacing the line breaks. {props.one}
98

10-
```bash
11-
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/mtls_certificates" \
12-
--header "X-Auth-Email: <EMAIL>" \
13-
--header "X-Auth-Key: <API_KEY>" \
9+
```sh
10+
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/mtls_certificates" \
11+
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
1412
--header "Content-Type: application/json" \
1513
--data '{
1614
"name": "example_ca_cert",
@@ -31,7 +29,7 @@ The response will return a UUID for the certificate. For example:
3129
"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
3230
"name": "example_ca_cert",
3331
"issuer": "O=Example Inc.,L=California,ST=San Francisco,C=US",
34-
"signature": "SHA256WithRSA"
32+
"signature": "SHA256WithRSA",
3533
...
3634
}
3735
}

0 commit comments

Comments
 (0)