Skip to content

Configuring Cloudflare for SaaS

Last updated View as Markdown Agent setup

Before you begin

Before you start creating custom hostnames:

  1. Add your zone to Cloudflare on a Free plan.
  2. Enable Cloudflare for SaaS for your zone.
  3. Review the Hostname prioritization guidelines. Wildcard custom hostnames behave differently than an exact hostname match.
  4. (optional) Review the following documentation:

Initial setup

When you first enable Cloudflare for SaaS, you need to perform a few steps prior to creating any custom hostnames.


1. Create fallback origin

The fallback origin is where Cloudflare will route traffic sent to your custom hostnames (must be proxied).

To create your fallback origin:

  1. Create a proxied A, AAAA, or CNAME record pointing to the IP address of your fallback origin (where Cloudflare will send custom hostname traffic).
Type Name IPv4 address Proxy status
A proxy-fallback 192.0.2.1 Proxied
  1. Designate that record as your fallback origin.

  1. In the Cloudflare dashboard, go to the Custom Hostnames page.

    Go to Custom Hostnames ↗

  2. For Fallback Origin, enter the hostname for your fallback origin.

  3. Select Add Fallback Origin.

Using the hostname of the record you just created, update the fallback origin value.

  1. Once you have added the fallback origin, confirm that its status is Active.

2. (Optional) Create CNAME target

The CNAME target — optional, but highly encouraged — provides a friendly and more flexible place for customers to route their traffic. You may want to use a subdomain such as customers.<SAAS_PROVIDER>.com.

Create a proxied CNAME that points your CNAME target to your fallback origin (can be a wildcard such as *.customers.saasprovider.com).

Type Name Target Proxy status
CNAME .customers proxy-fallback.saasprovider.com Proxied

Per-hostname setup

You need to perform the following steps for each custom hostname.

1. Plan for validation

Before you create a hostname, you need to plan for:

  1. Certificate validation: Upon successful validation, the certificates are deployed to Cloudflare’s global network.
  2. Hostname validation: Upon successful validation, Cloudflare proxies traffic for this hostname.

You must complete both these steps for the hostname to work as expected.

2. Create custom hostname

After planning for certification and hostname validation, you can create the custom hostname.

To create a custom hostname:

  1. In the Cloudflare dashboard, go to the Custom Hostnames page.

    Go to Custom Hostnames ↗

  2. Select Add Custom Hostname.

  3. Add your customer's hostname app.customer.com and set the relevant options, including:

  4. Select Add Custom Hostname.

  1. To create a custom hostname using the API, use the Create Custom Hostname endpoint.

    • Only Enterprise customers can use the certificate_authority parameter to specify a CA, the custom_certificate/custom_cert_bundle to upload a custom certificate, or wildcard to create a wildcard certificate. Refer to Plans.
    • You can leave the certificate_authority parameter empty to set it to "default CA". With this option, Cloudflare checks the CAA records before requesting the certificates, which helps ensure the certificates can be issued from the CA.

  2. For the newly created custom hostname, the POST response may not return the DCV validation token validation_records. It is recommended to make a second GET command (with a delay) to retrieve these details.

The response contains the complete definition of the new custom hostname.

Check when a custom hostname is ready

A custom hostname uses separate validation flows for hostname activation and certificate issuance.

API field What it means Ready value
result.status Cloudflare has validated the hostname and can proxy traffic for it. active
result.ssl.status Cloudflare has issued and deployed the certificate for the hostname. active

Treat a custom hostname as ready for production traffic when:

  • result.status is active.
  • result.ssl.status is active.
  • The hostname's DNS record points to your SaaS target.

A successful TLS handshake can happen before result.ssl.status changes to active if Cloudflare can present another matching certificate. Use the Custom hostname details endpoint as the source of truth for onboarding state. For more information, refer to Certificate and hostname priority.

3. Have customer create CNAME record

To finish the custom hostname setup, your customer needs to set up a CNAME record at their authoritative DNS that points to your CNAME target 1.

Your customer's CNAME record might look like the following:

mystore.example.com CNAME customers.saasprovider.com

This record would route traffic in the following way:

flowchart TD
accTitle: How traffic routing works with a CNAME target
A[Request to <code>mystore.example.com</code>] --> B[<code>customers.saasprovider.com</code>]
B --> C[<code>proxy-fallback.saasprovider.com</code>]

Requests to mystore.example.com would go to your CNAME target (customers.saasprovider.com), which would then route to your fallback origin (proxy-fallback.saasprovider.com).

Service continuation

If your customer is also using Cloudflare for their domain, they should keep their DNS record pointing to your SaaS provider in place for as long as they want to use your service.

For more details, refer to Remove custom hostnames.

Footnotes

  1. If you have regional services set up for your custom hostnames, Cloudflare always uses the processing region associated with your DNS target record (instead of the processing region of any custom origins).

    ↩

Was this helpful?