Connect Cloudflare for DNS validation

A certificate authority will only issue a certificate for a name if you prove that you control it. For an ordinary site that proof is a small file served over HTTP. For a wildcard certificate such as *.acme-studio.example, or for a site that is not reachable from the internet yet, the proof has to be a DNS record. SrvYard can create that record for you in Cloudflare, wait until the authority has seen it, and remove it again. For that it needs a Cloudflare connection.

This article shows how to create the Cloudflare token with the least permission that works, connect it, use it in the certificate panel, and keep it healthy. It is about validation only: SrvYard does not create the A or CNAME records that point your domain at the server. You still do that at your DNS host: see Add a domain, a free subdomain and DNS records.

Before you begin#

• A Cloudflare account that hosts the domain's DNS. The domain must be a zone in the account the token belongs to. SrvYard looks the zone up for every name on the certificate and refuses the request when it is missing.
• Permission to manage integrations. Connecting, editing and removing need integrations:manage, which owners and admins hold. Members who may manage a site's SSL settings can then pick the connection when they request a certificate.
• The domain on a site. See Create a site on your server, and read Wildcard certificates with DNS validation for the certificate side.

1. Create the token in Cloudflare#

In Cloudflare, open My Profile, then API Tokens, and create a token. SrvYard asks for exactly two permissions, and no more:

• Zone / DNS / Edit, so it can add and remove the validation record.
• Zone / Zone / Read, so it can find which zone a name belongs to.

Limit the token to the zones you will issue certificates for, under Zone Resources. A token that can edit every zone in the account works, but it can do much more than SrvYard needs. Copy the token when Cloudflare shows it. It is shown only once.

2. Connect it to SrvYard#

Open Settings > Integrations and scroll to DNS providers: "DNS providers SrvYard can use to validate domains for certificates, including wildcards."

1. Connect Cloudflare. Opens the connection panel.
2. A connection row. The name, the provider with its purpose (Cloudflare · DNS validation), the token as a masked hint, the Status, Used by and an actions menu.
3. Status. Connected with when it was last checked ("Checked 3d ago"). A token that Cloudflare no longer accepts shows the error here instead.

Press Connect Cloudflare.

1. Name. Any label, for example Cloudflare (acme-studio.example). It helps when you have more than one account.
2. API token. Paste the token. The text under the field repeats the permissions: Zone / DNS / Edit and Zone / Zone / Read on the zones you will issue certificates for.
3. Connect. SrvYard asks Cloudflare to confirm that the token is active before it saves it, and shows the answer if Cloudflare refuses. The token is stored encrypted and never shown again.

The Provider field only offers Cloudflare at the moment.

3. Use it for a certificate#

On a site, open SSL and press Get a free certificate. Choose DNS validation.

1. DNS validation. Chosen, instead of HTTP validation. The hostnames now include the wildcard names such as *.acme-shop.example, which HTTP validation cannot issue.
2. DNS integration. Choose the Cloudflare connection. SrvYard adds a TXT record for the validation, waits for the certificate authority to see it (about a minute) and removes it again. The panel says so too.

If you want the full walk-through of the certificate itself, with renewal and what to do when it fails, read Get a free Let's Encrypt certificate. Certificates that were issued with DNS validation are renewed with the same connection, so the connection has to stay healthy for as long as the certificate lives.

4. Keep it healthy#

Open the three-dot menu of the connection.

1. Edit. Rename the connection or replace the token, for example when you rotated it in Cloudflare. A new token is checked with Cloudflare before it is saved.
2. Verify again. Asks Cloudflare whether the token is still active. The result appears as a message and in the Status column.
3. Remove. Deletes the connection. SrvYard refuses while it validates certificates that renew automatically: "Delete those certificates first, or they could not renew." This protects you from a certificate that quietly fails to renew in two months.

The Used by column shows how many active certificates rely on the connection, or "Not used yet".

How safe is the token?#

The token is stored encrypted in SrvYard and is not sent back to your browser, not even to the people who connected it. SrvYard uses it only in the moment a certificate is requested or renewed, and only to add and remove the validation record in the zone of the name concerned. Because it can edit DNS in the zones you allowed, treat it as sensitive anyway: create a token only for SrvYard, name it clearly in Cloudflare, limit it to the zones you need, and set an expiry date you will remember. If you ever suspect it leaked, delete it in Cloudflare first, which stops all use at once, and then create a new one and edit the connection.

Each connection is a separate token, so you can keep one per Cloudflare account, or one per client zone if you run an agency, and give each a name that says which.

When not to use it#

You do not need a DNS connection for an ordinary single-domain certificate: HTTP validation needs no DNS access at all and works as soon as the name points at the server. Reach for Cloudflare when you want a wildcard, when the site is not live yet, when port 80 cannot be open, or when you would rather not depend on the name already resolving to this server during a migration.

Troubleshooting#

• "Has no zone in the Cloudflare account of this integration". The domain is not a zone in the connected account, or the token is not allowed to see it. Add the domain to Cloudflare, widen Zone Resources of the token, or connect the right account.
• Cloudflare refuses the token when I connect. It is expired, was copied with a space, or lacks one of the two permissions. Create a new one.
• Status shows an error some weeks after it worked. The token expired or was revoked. Edit the connection and paste a new token, then Verify again.
• The wildcard hostname is not offered. You are on HTTP validation. Switch the choice to DNS validation first.
• Validation times out. Cloudflare accepted the record but the authority did not see it in time. Check that the domain's nameservers really are Cloudflare's, and try again.
• Remove is refused. Active certificates renew with this connection. Delete them or move them to another connection first.

Related#

• Wildcard certificates with DNS validation: the certificate side.
• Get a free Let's Encrypt certificate: HTTP validation, renewal and failures.
• Add a domain, a free subdomain and DNS records: the records that point the name at your server.
• How renewals work and what to do when one fails: why the connection must stay healthy.