Cloudflare Custom Hostname Management

During the year of 2019 I led a Content Delivery Network (CDN) project. The first phase of the project involved migrating existing web assets that were on Akamai, to Cloudflare. During this time, I had the opportunity to really get comfortable with CDN technology and more specifically the enterprise services offered by Cloudflare. Like most CDN vendors, Cloudflare offers a number of services. This blog will focus on the management of custom SSL/TLS certificates for the Custom Hostname (SSL for SaaS) service offered by Cloudflare.

Cloudflare’s SSL for SaaS service allows easy deployment and management of SSL certificate lifecycles which encompass the initial issuance and automated renewal of certificates. However, in some use cases custom SSL certificates are preferred. These use cases typically involve Extended Validation Certificates or security prioritzation over the automated generation of private keys by third parties.

This blog will focus on a solution to manage SSL certificates for Cloudflare’s custom hostname service using custom certificates. Unlike the fully managed service, using custom certificates demands the use of the custom hostname API to upload certificates.* I have developed 3 python scripts that manage this solution:

1. Adding a new custom hostname
2. Review custom hostname certificate details
3. Update custom hostname certificates

The repository for these scripts can be found here.

• EDIT : Cloudflare has subsequently enabled custom certificates to be uploaded from the dashboard

SSL for SaaS

To benefit from Cloudflare’s SSL for SaaS service, one would need an enterprise account and the service would need to be activated by Cloudflare. Once this has been accomplished, one can access the SSL for SaaS service via the Cloudflare dashboard.

If one uses the fully managed SSL service, one would simply create a new custom hostname using the below form under the Custom Hostnames tab.

Since we are focusing on custom certificates, we will be discussing managing custom hostname's with custom certificates.

Adding a new custom hostname

The objective when adding a new custom hostname, with a custom certificate, is to ensure that the custom hostname has been added successfully and the SSL status is active. On the Cloudflare dashboard, you would want to see something similar to the below. ( the custom origin server has been blurred out for security reasons )

Running the Add New Custom Hostname script

The python script I have developed for adding new custom hostname's can be viewed here. I will briefly explain how this script works.

This script takes the following arguments:

1. Name of the hostname to add
2. Name of the origin server for the hostname
3. The ssl certificate associated with the hostname
4. The associated ssl key
5. The Cloudflare zone where the custom hostname should be added

Displaying the help options on the script will show all the available argument format

usage: add_new_custom_hostname.py [-h] -n HOSTNAME -o ORIGIN -c CERTIFICATE -k KEY -z ZONE

optional arguments:
-h, --help show this help message and exit
-n HOSTNAME, --hostname HOSTNAME
the hostname to add as a custom hostname
-o ORIGIN, --origin ORIGIN
the origin of the hostname
-c CERTIFICATE, --certificate CERTIFICATE
the certificate file to upload
-k KEY, --key KEY the key file to upload
-z ZONE, --zone ZONE the zone to add custom hostname

Running the command will look similar to this:

./add_new_custom_hostname.py -n hostname -o origin_server_name -c certificate.crt -k key.key -z zonename

The script will analyze the certificate, making sure the user supplied certificate matches the Common Name or Alternative Name. If it’s a wildcard certificate, it will ensure the Common Names domain and the supplied hostname domain match. It will ensure the key and the certificate are the correct pair. It will then check Cloudflare to ensure the hostname does not already exist. Once these checks have passed, it will prompt the user as to whether they would like to continue with the procedure of adding this new hostname to the SSL for SaaS service. If the user types yes, the hostname and custom certificate will be added to Cloudflare and any names that happen to share the certificate on Cloudflare will be shown. For a more detailed wiki on this procedure, click here.

Review a Custom Hostname certificate details

The Cloudflare dashboard does not have the ability to review the certificate details for a custom hostname. When the certificate is due to expire, Cloudflare will send an automated email to remind one of the expirations. To view the details of a custom hostname certificate, the Cloudflare API for SSL for SaaS will also need to be used.

Running the Review Custom Hostname Certificate script

The python script for reviewing a custom hostname certificate can be viewed here . Here’s an explanation of how this script works.

This script takes the following arguments:

1. Name of the hostname to check
2. The Cloudflare zone where the custom hostname exists

Displaying the help options on the script will show all the available argument formats

usage: get_cert_info_cf.py [-h] -n HOSTNAME -z ZONE

optional arguments:
-h, --help show this help message and exit
-n HOSTNAME, --hostname HOSTNAME
the hostname to check
-z ZONE, --zone ZONE the zone to check

Running the command will look similar to this:

./get_cert_info_cf.py -n hostname -z zone

The output expected would look something like this:

The script will connect to Cloudflare and find the details for the specified hostname. It will display the following details:

1. The zone name
2. The hostname
3. The associated hostnames for the certificate
4. The SSL status
5. When the certificate was issued
6. When the certificate expires
7. When the certificate was uploaded to cloudflare
8. The origin server
9. The certificate serial number

The script will also display what hostname's happen to share the specified hostname's certificate. A more detailed explanation via a wiki can be viewed here.

Update a Custom Hostname Custom Certificate

To update custom certificates, the Cloudflare API for SSL for SaaS will also need to be used. Essentially the only way to update custom certificates for custom hostname's is to remove the hostname and re-add it with the new certificate. Luckily, with the API call, this can be done in a matter of seconds and one should not experience any degradation of service to the site associated with the custom hostname.

Running the Update A Custom Hostname Certificate script

The python script for updating a custom hostname certificate can be viewed here. Here’s an explanation of how this script works.

The script will take the following arguments:

1. Name of the hostname to add
2. The ssl certificate associated with the hostname
3. The associated ssl key
4. The Cloudflare zone where the custom hostname should be added

Displaying the help options on the script will show all the available argument formats.

usage: update_cert_cf.py [-h] -n HOSTNAME -c CERTIFICATE -k KEY -z ZONE

optional arguments:
-h, --help show this help message and exit
-n HOSTNAME, --hostname HOSTNAME
the hostname to check
-c CERTIFICATE, --certificate CERTIFICATE
the certificate file to upload
-k KEY, --key KEY the key file to upload
-z ZONE, --zone ZONE the zone to check

Running the command will look similar to this:

./update_cert_cf.py -n hostname -ccertificate.crt -k key.key -z zonename

The output expected would look something like this:

The script will analyze the certificate, making sure the user supplied certificate matches the Common Name or Alternative Name. If it’s a wildcard certificate, it will ensure the Common Names domain and the supplied hostname domain match. It will ensure the key and the certificate are the correct pair. It will then check Cloudlfare to ensure the hostname does not already exist. It will also display all the other names that happen to share the certificate. These names will also be updated with this certificate. This ensures that the updates only happen once and all names associated with the certificate are updated as well.

After these checks have passed, it will prompt the user as to whether they would like to continue with the procedure of updating the certificate. If the user types ‘yes’, the script will begin updating all the names associated with the certificate. This will be done one by one i.e if there are multiple names to update, it will remove one name and re-add it with the new certificate before moving onto the next name. A more detailed explanation via a wiki can be viewed here.

Conclusion

Understanding how Cloudflare manages services for enterprise customers can be tricky. SSL for SaaS and custom hostname management, especially with custom certificates, is one of these tricky services to get right. I’m hoping that this blog and accompanying scripts can help or steer others in the right direction when managing their own enterprise Cloudflare SSL for SaaS solutions. Feel free to contact me on the contact page for any feedback or questions on this solution.