Cloudflare Docs
SSL/TLS
SSL/TLS
Visit SSL/TLS on GitHub
Set theme to dark (⇧+D)

Custom hostnames

On January 23, 2023, Cloudflare will stop using DigiCert as an issuing certificate authority (CA) for new custom hostname certificates. This will not affect existing custom hostname certificates.

On January 31, 2023, Cloudflare will stop using DigiCert as the CA for custom hostname certificate renewals. This will not affect existing custom hostname certificates, but only certificate renewals.

​​ Summary of changes

This table provides a summary of the differences between DigiCert and our other CAs.

AreaDigiCertOther CAsActions required
Domain Control
Validation (DCV)
To get a certificate issued for a wildcard custom hostname, one TXT DCV record is required to complete Domain Control Validation.To get a certificate issued for a wildcard custom hostname, two TXT DCV records will be required to complete validation.Wildcard custom hostnames will require additional DCV tokens. Non-wildcard custom hostnames will automatically renew as long as the hostname is proxying through Cloudflare.
APICustomers can choose “digicert” as the issuing CA when using the custom hostnames API.Customers can only choose “lets_encrypt” or “google” when using the custom hostnames API.If you are currently using DigiCert as the issuing CA when creating custom hostnames, switch your integration to use Let’s Encrypt or Google.
DCV MethodsCNAME and Email DCV are available.CNAME and Email DCV will be deprecated. Customers will be required to use HTTP or DNS DCV.When certificates come up for renewal that are using CNAME or Email DCV, Cloudflare will automatically choose HTTP DCV as the default method for non-wildcard custom hostnames and TXT DCV for wildcard custom hostnames.
Validity periodCustom hostname certificates have a 1 year validity period.Custom hostnames certificates will have a 90 day validity period.If you are using wildcard custom hostnames, your customers will need to place DCV tokens at their DNS provider more frequently. Non-wildcard custom hostname certificates will automatically renew, as long as the hostname is actively proxying through Cloudflare. Cloudflare will handle the renewals at a more frequent rate.

​​ Domain Control Validation (DCV) updates

CNAME and Email DCV will be deprecated on January 23, 2023, requiring customers to use either HTTP, Delegated DCV, or TXT DCV.

Also, the maximum validity period for certificates will be decreased from 1 year to 90 days. This means that certificates will be renewed - and require DCV - more frequently.

​​ Required actions

​​ Before January 23, 2023

If your system integrates with the SSL for SaaS API to create custom hostnames, you will need to update:

  • The value sent in the "certificate_authority" field under the SSL object. Your integration should either use Google Trust Services ("google") or Let’s Encrypt ("lets_encrypt").
  • The value sent in the "method" field under the SSL object. Your integration should either use "http" (only available for non-wildcard hostnames) or "txt".

​​ Before January 31, 2023

We recommend that you migrate all your current custom hostnames away from DigiCert before January 31, 2023. This give you the control to migrate custom hostnames to the new system in a controlled manner instead of having Cloudflare manage the offboarding when the certificates come up for renewal.

​​ Identify certificates

To identify certificates that are coming up for renewal, set up notifications for SSL for SaaS Custom Hostnames Alert events.

You can also send a GET request to the API and look for certificates with a ssl_status of pending_validation and a certificate_authority of digicert within the SSL object.

To find wildcard custom hostnames specifically that are using DigiCert certificates, send a GET request and include ?certificate_authority=digicert&wildcard=true in the request parameter.

​​ Update values

You should update the following values:

  • Certificate Authority: When you update this value, it will immediately reissue the certificate. Cloudflare will continue serving the previous certificate until the new one is validated. If the certificate was previously using DigiCert and you do not update this value, Cloudflare will choose the issuing CA upon renewal.

    • Dashboard: Update the value for SSL certificate authority to either be Let’s Encrypt or Google Trust Services.
    • API: Update the value sent in the "certificate_authority" field under the SSL object to either be "lets_encrypt" or "google".
  • DCV Method: You can only update this value when your certificate is up for renewal. If your certificate was previously using Email or CNAME validation and you do not update this value, Cloudflare will automatically set your DCV method to TXT or HTTP when the custom hostname comes up for renewal. We will use HTTP validation for non-wildcard custom hostname renewals and TXT-based DCV for wildcard custom hostname renewals.


​​ Non-wildcard custom hostnames

For non-wildcard hostnames, you can use HTTP DCV to automatically perform DCV as long as the custom hostname is proxying traffic through Cloudflare. Cloudflare will complete DCV on the hostname’s behalf by serving the HTTP token.

If your hostname is using another validation method, you will need to update the "method" field in the SSL object to be "http".

If the custom hostname is not proxying traffic through Cloudflare, then the custom hostname domain owner will need to add the TXT or HTTP DCV token for the new certificate to validate and issue. As the SaaS provider, you will be responsible for sharing this token with the custom hostname domain owner.

​​ Wildcard custom hostnames

To validate a certificate on a wildcard custom hostname, you should either set up Delegated DCV or TXT-based DCV.

Cloudflare recommends Delegated DCV as it is much simpler for you and your customers.

If you choose TXT-based DCV, Cloudflare requires two TXT DCV tokens - one for the apex and one for the wildcard - to be placed at your customer’s authoritative DNS provider in order for the wildcard certificate to issue or renew.

These two tokens are required because Let’s Encrypt and Google Trust Services follow the ACME Protocol, which requires one DCV token to be placed for every hostname on the certificate.

If your hostname is using another validation method, you will need to update the "method" field in the SSL object to be "txt".

These tokens can be fetched through the API or the dashboard when the certificates are in a pending validation state during custom hostname creation or during certificate renewals.

You can access these tokens using the API with the GET custom hostnames endpoint.

For example, here are two tokens highlighted in the API response for a wildcard custom hostname.

Response
{
"result": [
{
"id": "<HOSTNAME_ID>",
"hostname": "<HOSTNAME>",
"ssl": {
"id": "<CERTIFICATE_ID>",
"type": "dv",
"method": "txt",
"status": "pending_validation",
"validation_records": [
{
"status": "pending",
"txt_name": "_acme-challenge.<HOSTNAME>",
"txt_value": "gESljTB8fBT1mIuoEASU0qcK-oTd46baarnU_ZGjJIY"
},
{
"status": "pending",
"txt_name": "_acme-challenge.<HOSTNAME>",
"txt_value": "Pd8ViwX8KuA78kLbQHGmdEh4tQSpHBRxiNuJOYStEC0"
}
],
"settings": {
"min_tls_version": "1.0"
},
"bundle_method": "ubiquitous",
"wildcard": true,
"certificate_authority": "google"
},
"status": "pending",
"ownership_verification": {
"type": "txt",
"name": "_cf-custom-hostname.<HOSTNAME>",
"value": "ac4a9a9d-5469-44cb-9d76-cea7541c9ff8"
},
"ownership_verification_http": {
"http_url": "http://<HOSTNAME>/.well-known/cf-custom-hostname-challenge/fabdf93c-a4ce-4075-9f3f-c553a5f93bed",
"http_body": "ac4a9a9d-5469-44cb-9d76-cea7541c9ff8"
},
"created_at": "2022-10-06T19:35:33.143257Z"
}
]
}
  1. Log in to the Cloudflare dashboard and select your account.
  2. Select your Cloudflare for SaaS application.
  3. Navigate to SSL/TLS > Custom Hostnames.
  4. Select a hostname.
  5. Copy the values for Certificate validation TXT name and Certificate validation TXT value.

If you had previously created a wildcard custom hostname, you would need to copy the values for two different validation TXT records.

Your customers should place these at their authoritative DNS provider under the "_acme-challenge" DNS label. Once these TXT records are in place, validation and certificate issuance will automatically complete.

​​ Actions required

As the SaaS provider, you will be responsible for sharing these DCV tokens with your customers. Let’s Encrypt DCV tokens are valid for 7 days and Google Trust Services tokens are valid for 14 days. We recommend that you make this clear to your customers, so that they add the tokens in a timely manner. If your customers take longer than the token validity period to add the record then you will need to fetch updated tokens and share those in order for the certificate to validate and issue.

Once your customer has added these tokens, the certificate status will change to Active. Cloudflare will periodically check if the DCV tokens have been placed according to the certificate validation schedule. Once your customer has added the records, you can make a no-change call to the custom hostnames API to restart the validation schedule for a specific hostname.