TLS Management

Mutual TLS (mTLS) ↗ adds an extra layer of protection to application connections by validating certificates on the server and the client. When building a SaaS application, you may want to enforce mTLS to protect sensitive endpoints related to payment processing, database updates, and more.

Minimum TLS Version only allows HTTPS connections from visitors that support the selected TLS protocol version or newer. Cloudflare recommends TLS 1.2 to comply with the Payment Card Industry (PCI) Security Standards Council. As a SaaS provider, you can control the Minimum TLS version for your zone as a whole, as well as for individual custom hostnames.

Cipher suites are a combination of ciphers used to negotiate security settings during the SSL/TLS handshake ↗. As a SaaS provider, you can specify configurations for cipher suites on your zone as a whole and cipher suites on individual custom hostnames via the API.

Warning

When you issue a custom hostname certificate with wildcards enabled, any cipher suites or Minimum TLS settings applied to that hostname will only apply to the direct hostname.

However, if you want to update the Minimum TLS settings for all wildcard hostnames, you can change Minimum TLS version at the zone level.

Enable mTLS

Once you have added a custom hostname, you can enable mTLS by using Cloudflare Access. Go to Cloudflare Zero Trust ↗ and add mTLS authentication with a few clicks.

Note

Currently, you cannot add mTLS policies for custom hostnames using API Shield.

Minimum TLS Version

Note

While TLS 1.3 is the most recent and secure version, it is not supported by some older devices. Refer to Cloudflare's recommendations when deciding what version to use.

Scope

Minimum TLS version exists both as a zone-level setting (under Edge certificates > Minimum TLS Version) and as a custom hostname setting. What this implies is:

• For custom hostnames created via API, it is possible not to explicitly define a value for min_tls_version. When that is the case, whatever value is defined as your zone's minimum TLS version will be applied. To confirm whether a given custom hostname has a specific minimum TLS version set, use the following API call.

Check custom hostname settings TLS settings

Required API token permissions

At least one of the following token permissions is required:

• SSL and Certificates Write
• SSL and Certificates Read

Custom Hostname Details

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_hostnames/$CUSTOM_HOSTNAME_ID" \
  --request GET \
  --header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
  --header "X-Auth-Key: $CLOUDFLARE_API_KEY"

Response example

  "success": true,
  "result": {
    "id": "<CUSTOM_HOSTNAME_ID>",
    "ssl": {
      "id": "<CERTIFICATE_ID>",
      "bundle_method": "ubiquitous",
      "certificate_authority": "<CERTIFICATE_AUTHORITY>",
      "custom_certificate": "",
      "custom_csr_id": "",
      "custom_key": "",
      "expires_on": "",
      "hosts": [
        "app.example.com",
        "*.app.example.com"
      ],
      "issuer": "",
      "method": "http",
      "settings": {},
      "signature": "SHA256WithRSA",
      "type": "dv",
      "uploaded_on": "2020-02-06T18:11:23.531995Z",
      "validation_errors": [
        {
          "message": "SERVFAIL looking up CAA for app.example.com"
        }
      ],
      "validation_records": [
        {
          "emails": [
            "administrator@example.com",
            "webmaster@example.com"
          ],
          "http_body": "ca3-574923932a82475cb8592200f1a2a23d",
          "http_url": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt",
          "txt_name": "_acme-challenge.app.example.com",
          "txt_value": "810b7d5f01154524b961ba0cd578acc2"
        }
      ],
      "wildcard": false
    },
  }

• Whenever you make changes to a custom hostname via dashboard, the value that is set for Minimum TLS version will apply. If you have a scenario as explained in the bullet above, the dashboard change will override the zone-level configuration that was being applied.

• For custom hostnames with wildcards enabled, the direct custom hostname you create (for example, saas-customer.test) will use the hostname-specific setting, while the others (sub1.saas-customer.test, sub2.saas-customer.test, etc) will default to the zone-level setting.

Setup

Minimum TLS version for your zone

Refer to Minimum TLS version - SSL/TLS.

Minimum TLS version for custom hostname

1. Log in to the Cloudflare dashboard ↗ and select your account and website.
2. Go to SSL/TLS > Custom Hostnames.
3. Find the hostname to which you want to apply Minimum TLS Version. Select Edit.
4. Choose the desired TLS version under Minimum TLS Version and select Save.

Cipher suites

For security and regulatory reasons, you may want to only allow connections from certain cipher suites. Cloudflare provides recommended values and full cipher suite reference in our Cipher suites documentation.

Restrict cipher suites for your zone

Refer to Customize cipher suites - SSL/TLS.

Restrict cipher suites for custom hostname

In the API documentation, refer to SSL properties of a custom hostname.

When making the request, make sure to include type and method within the ssl object, as well as the settings specifications.

Alerts for mutual TLS certificates

You can configure alerts to receive notifications before your mutual TLS certificates expire.

Access mTLS Certificate Expiration Alert

Who is it for?

Access customers that use client certificates for mutual TLS authentication. This notification will be sent 30 and 14 days before the expiration of the certificate.

Other options / filters

None.

Included with

Purchase of Access and/or Cloudflare for SaaS.

What should you do if you receive one?

Upload a renewed certificate.

Refer to Cloudflare Notifications for more information on how to set up an alert.