Configuring Cloudflare for SaaS
Prerequisites
Before you can start creating custom hostnames, you need to have access to Cloudflare for SaaS.
If you have not used the Cloudflare API previously, review our API Quickstart.
If there are multiple proxied DNS records for one zone, Cloudflare must prioritize which record controls the zone settings and associated origin server. Adding a new custom hostname may take priority over your current settings or cause your settings to no longer apply. To prevent overriding or voiding your settings, review Hostname priority (Cloudflare for SaaS)
Step 1 — Create fallback origin and CNAME target
The fallback origin is where Cloudflare will route traffic sent to your custom hostnames (must be proxied).
The CNAME target — optional, but highly encouraged — provides a friendly and more flexible place for customers to route their traffic.
We suggest using a domain other than your main company domain (example.cloud instead of example.com) to lower risk and add flexibility to your custom hostname management.
Create a new application and select the Free plan.
- A proxied A or AAAA record pointing to the IP address of your fallback origin (where Cloudflare will send custom hostname traffic).
- A CNAME record that points your CNAME target to your fallback origin (can be a wildcard such as
*.customers.saasprovider.com).
| Record | Type | Name | Content |
|---|---|---|---|
| Fallback origin | A | proxy-fallback.saasprovider.com | 192.0.2.1 |
| CNAME target | CNAME | *.customers.saasprovider.com | proxy-fallback.saasprovider.com |
Enable Custom Hostnames for your zone:
- If you are an Enterprise customer, upgrade your zone to an Enterprise plan and contact your Customer Success Manager to enable Cloudflare for SaaS Certificates.
- If you are not an Enterprise customer, go to SSL/TLS > Custom Hostnames to enable Cloudflare for SaaS.
Set the Fallback Origin via either the dashboard or API.
Using the dashboard
- Navigate to SSL/TLS > Custom Hostnames.
- In the Custom Hostnames card, enter the hostname for your fallback origin.
- Click Add.
Using the API
Using the hostname from the A or AAAA record you just created, update the fallback origin value.
Step 2 — Review validation and verification options
Each Custom Hostname requires successful Certificate Validation and Hostname Verification.
- Certificate Validation: Upon successful validation, the certificates are deployed to Cloudflare’s edge network.
- Hostname Verification: Upon successful validation, Cloudflare proxies traffic for this hostname.
Depending on which method you select for each of these options, additional steps might be required for you and your customers.
Step 3 — Issue certificate
Once your account has been provisioned, you are ready to issue certificates.
For each custom hostname certificate you request, Cloudflare issues two certificates that are bundled in chains that maximize browser compatibility (unless you upload custom certificates). The primary certificate uses a P-256 key, is SHA-2/ECDSA signed, and will be presented to browsers that support elliptic curve cryptography (ECC). The secondary or fallback certificate uses an RSA 2048-bit key, is SHA-2/RSA signed, and will be presented to browsers that do not support ECC.
Once issued, certificates are valid for one year. Renewals depend on your chosen method for Domain Control Validation. To create a custom hostname using the API, use a POST command on the The response contains the complete definition of the new custom hostname.Using the dashboard
app.customer.com and set the relevant options, including:*.<custom-hostname> SAN to the custom hostname certificate. For more details, refer to Hostname priority.Using the API
/zone/:zone_id/custom_hostnames endpoint.
Step 4 — Monitor and view certificates
Once you issue certificates, Cloudflare will initiate the domain validation process using the method you specified.
With a CNAME in place, the entire process — from validation to issuance to edge deployment — completes in approximately 90 seconds.
Monitor certificate status
For help tracking a certificate’s status, refer to Monitor certificates.
View certificates
Once domain validation has been completed, the certificates will be issued and distributed to Cloudflare’s edge.
To view these certificates, use openssl or your browser. The command below can be used in advance of your customer pointing the app.example.com hostname to the edge (provided validation was completed).
$ openssl s_client -servername app.example.com -connect $CNAME_TARGET:443 </dev/null 2>/dev/null | openssl x509 -noout -text | grep app.example.com
Step 5 — Have customer create a CNAME record
Your customer needs to set up a CNAME record at their DNS provider that points to your CNAME target. For an existing site, ensure your custom hostname and certificate are verified and valid prior to completing this step. Shifting traffic before the certificate has been issued may cause an insecurity in your domain.
For example:
app CNAME john.customers.saasprovider.comThis routes traffic from app.customer.com to your origin.
Step 6 — Offboard custom hostnames
As a SaaS provider, you must remove a customer’s custom hostname from your zone if they decide to churn. This is especially important if your end customers are using Cloudflare because if the custom hostname changes the DNS target to point away from your SaaS zone, the custom hostname will continue to route to your service. This is a result of the custom hostname priority logic.
Delete custom hostname
Using the dashboard
Log in to the Cloudflare dashboard and select your account and website.
Select SSL/TLS > Custom Hostnames.
Select the custom hostname and select Delete.
A confirmation window will appear. Acknowledge the warning and select Delete again.
Using the API
To delete a custom hostname and any issued certificates using the API, use a DELETE command on the DELETE zones/:zone_identifier/custom_hostnames/:identifier endpoint.