Skip to content

[ZT] Update custom cert API calls #19703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Feb 4, 2025
Merged

[ZT] Update custom cert API calls #19703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7cd7694
Update API variables
maxvp Feb 3, 2025
036a05f
Rearrange steps
maxvp Feb 3, 2025
31caaa1
Edit step 3
maxvp Feb 3, 2025
9e58f40
Add optional step 4
maxvp Feb 3, 2025
6d44945
Edit step 5
maxvp Feb 3, 2025
efb2b1a
Edit partial
maxvp Feb 3, 2025
4db2b3b
Apply suggestions from code review
maxvp Feb 4, 2025
4e24c23
Redact cert contents
maxvp Feb 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 96 additions & 85 deletions ...e-one/connections/connect-devices/user-side-certificates/custom-certificate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,94 +65,105 @@ openssl x509 -in <CUSTOM-ROOT-CERT>.pem -text

<Tabs syncKey="dashPlusAPI">

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

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

</TabItem>

<TabItem label="API">
1. Verify that the certificate is installed on your devices.
2. <Render file="upload-mtls-cert" params={{ one: " " }} />
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/).
```bash {10}
curl --request PATCH \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/configuration" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"settings": {
"custom_certificate": {
"enabled": true,
"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60"
}
}
}'
```
The response will return the pending status of the certificate. For example:
```json {13}
{
"success": true,
"errors": [],
"messages": [],
"result": {
"settings": {
"antivirus": {},
"block_page": {},
"custom_certificate":
{
"enabled": true,
"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60",
"binding_status": "pending_deployment",
"qs_pack_id": "50a78g31-a5b5-4k58d-a6ed-b0ac17da9k05"
},
"tls_decrypt": {},
"activity_log": {},
"browser_isolation": {},
"fips": {},
},
},
"created_at": "2014-01-01T05:20:00.12345Z",
"updated_at": "2014-01-01T05:20:00.12345Z"
}
```
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/).
```bash
curl --request POST \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/certificates/{certificate_id}/activate" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"
```
The response will return the certificate and its current deployment status. For example:
```json {6,12}
{
"errors": [],
"messages": [],
"success": true,
"result": {
"binding_status": "active",
"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",
"created_at": "2014-01-01T05:20:00.12345Z",
"expires_on": "2014-01-01T05:20:00.12345Z",
"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",
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
"in_use": true,
"issuer_org": "Example Inc.",
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
"type": "gateway_managed",
"updated_at": "2014-01-01T05:20:00.12345Z",
"uploaded_on": "2014-01-01T05:20:00.12345Z"
}
}
```
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.
</TabItem>
</TabItem>

<TabItem label="API">

1. <Render file="upload-mtls-cert" params={{ one: " " }} />

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.

```sh
curl --request POST \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates/$CERTIFICATE_ID/activate" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

The response will return the certificate and a `pending_deployment` binding status. For example:

```json {12}
{
"errors": [],
"messages": [],
"success": true,
"result": {
"in_use": false,
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
"certificate": "-----BEGIN CERTIFICATE-----\\n ... \\n-----END CERTIFICATE-----\\n",
"issuer_org": "Example Inc.",
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
"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",
"binding_status": "pending_deployment",
"type": "custom",
"updated_at": "2014-01-01T05:20:00.12345Z",
"uploaded_on": "2014-01-01T05:20:00.12345Z",
"created_at": "2014-01-01T05:20:00.12345Z",
"expires_on": "2014-01-01T05:20:00.12345Z"
}
}
```

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

```sh
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/certificates/$CERTIFICATE_ID \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

```json {12}
{
"errors": [],
"messages": [],
"success": true,
"result": {
"in_use": false,
"id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
"certificate": "-----BEGIN CERTIFICATE-----\\n ... \\n-----END CERTIFICATE-----\\n",
"issuer_org": "Example Inc.",
"issuer_raw": "O=Example Inc.,L=California,ST=San Francisco,C=US",
"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",
"binding_status": "available",
"type": "custom",
"updated_at": "2014-01-01T05:20:00.12345Z",
"uploaded_on": "2014-01-01T05:20:00.12345Z",
"created_at": "2014-01-01T05:20:00.12345Z",
"expires_on": "2014-01-01T05:20:00.12345Z"
}
}
```

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

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:

```sh {9}
curl --request PATCH \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/configuration" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"settings": {
"certificate": {
"id": "$CERTIFICATE_ID",
"in_use": true
}
}
}'
```

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.

</TabItem>

</Tabs>

:::caution[Private key visibility]
Expand Down
14 changes: 7 additions & 7 deletions ...ocs/cloudflare-one/connections/connect-devices/user-side-certificates/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ Send a `POST` request to the [Create Zero Trust certificate](/api/resources/zero

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

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

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

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

```sh
curl --request PUT \
'https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/configuration' \
'https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/configuration' \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{
"settings": {
"certificate": {
"id": "<CERTIFICATE_ID>",
"id": "$CERTIFICATE_ID",
"in_use": true
}
}
Expand Down
12 changes: 5 additions & 7 deletions src/content/partials/cloudflare-one/upload-mtls-cert.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
---
inputParameters: param1

---

import { Markdown } from "~/components"
import { Markdown } from "~/components";

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}

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