Deploy custom certificate
Enterprise customers who do not wish to install a Cloudflare certificate have the option to upload their own root certificate to Cloudflare. This feature is sometimes referred to as Bring Your Own Public Key Infrastructure (BYOPKI). Gateway will use your uploaded certificate to encrypt all sessions between the end user and Gateway, enabling all HTTPS inspection features that previously required a Cloudflare certificate. You can upload multiple certificates to your account, but only one can be active at any given time. You also need to upload a private key to intercept domains with JIT certificates and to enable the block page.
You can upload up to five custom root certificates. If your organization requires more than five certificates, contact your account team.
Before you generate a custom root CA, make sure you have OpenSSL ↗ installed.
-
Open a terminal.
-
Create a directory for the root CA and change into it.
Terminal window mkdir -p /root/customcacd /root/customca -
Generate a private key for the root CA.
Terminal window openssl genrsa -out <CUSTOM-ROOT-PRIVATE-KEY>.pem 2048 -
Generate a self-signed root certificate.
Terminal window openssl req -x509 -sha256 -new -nodes -key <CUSTOM-ROOT-PRIVATE-KEY>.pem -days 365 -out <CUSTOM-ROOT-CERT>.pem
When preparing your certificate and private key for upload, be sure to remove any unwanted characters, such as mismatching subdomains in the certificate's common name. To review the private key, run the following command:
openssl rsa -in <CUSTOM-ROOT-PRIVATE-KEY>.pem -textTo review the certificate, run the following command:
openssl x509 -in <CUSTOM-ROOT-CERT>.pem -text- In Zero Trust ↗, go to Settings > Resources.
- In Certificates, select Manage.
- Select Upload certificate.
- Enter the private key and SSL certificate you generated or select Paste certificate from file to upload them from a file.
- Select Generate certificate.
You can now use the generated custom root certificate for inspection.
- Verify that the certificate is installed on your devices.
-
Use the Upload mTLS certificate endpoint to upload the certificate and private key to Cloudflare. The certificate must be a root CA, formatted as a single string with
\nreplacing the line breaks.Terminal window curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/mtls_certificates" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>" \--header "Content-Type: application/json" \--data '{"name": "example_ca_cert","certificates": "-----BEGIN CERTIFICATE-----\nXXXXX\n-----END CERTIFICATE-----","private_key": "-----BEGIN PRIVATE KEY-----\nXXXXX\n-----END PRIVATE KEY-----","ca": true}'The response will return a UUID for the certificate. For example:
{"success": true,"errors": [],"messages": [],"result": {"id": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60","name": "example_ca_cert","issuer": "O=Example Inc.,L=California,ST=San Francisco,C=US","signature": "SHA256WithRSA"...}} - Deploy the certificate in Gateway using the certificate's UUID with the Patch Zero Trust account configuration endpoint.
The response will return the pending status of the certificate. For example:
Terminal window 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"}}}'{"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"} - Activate the certificate for use in inspection with the Activate a Zero Trust certificate endpoint.
The response will return the certificate and its current deployment status. For example:
Terminal window 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>"{"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.
To use a custom root certificate you generated and uploaded to Cloudflare, refer to Activate a root certificate.
If Gateway returns an HTTP Response Code: 526 after deploying a custom certificate, you can troubleshoot errors with our FAQ.