AcmeAlias

DNS-01, without the credentials

Keep your DNS key. We answer the challenge.

You have been here. A wildcard needs a DNS-01 challenge, that challenge needs an API token, and the token that proves you control one name can rewrite every record you own. So it goes into the load balancer's configuration, and into the backup of that configuration, and you decide not to think about it. It is ugly, and it is unsafe.

There is a better shape for this, and it is already built: publish one CNAME, once, by hand. After that every renewal is invisible to you, and the key never leaves your DNS provider — because we never ask for one.

The clients you already run

We speak the acme-dns protocol, so these need a few lines of configuration and nothing installed. The exact lines are step 5 below.

Trademarks of Traefik Labs, the Cloud Native Computing Foundation, the Electronic Frontier Foundation and the Internet Security Research Group. They are here to say which software works with this service; no endorsement by any of them is claimed or implied.

The whole integration, and how to check it

Six steps, once per domain. Everything after step 4 is your ACME client doing what it already does, and steps 3 and 4 are two records published once — the delegation that makes this work, and the CAA record that bounds what it lets us do.

  1. Add the domain

    In the console, add the name you want certificates for.

    In the console, create a project and add the name you want certificates for — shop.example.com, or *.example.com for a wildcard. A wildcard and its apex share one record, so example.com and everything under it is still a single CNAME.

  2. We issue you an alias

    We give you one random label inside our zone, created with the domain and never changed.

    One randomly generated label inside our zone — edgedns.cloud, which is delegated to us and holds nothing but these — created with the domain and never re-labelled. The console shows it on the domain's row.

    The label is random rather than derived from your domain, and that is deliberate: a label anybody could compute from a name would turn our zone into a membership oracle, answering "is this company a customer" to whoever asks.

  3. In your DNS provider, add one CNAME record

    One CNAME at _acme-challenge, published once and never touched again.

    Wherever your zone lives now — no account with us, no API token, no delegation of anything else:

    For a wildcard, the record is at _acme-challenge.example.com — the * is not part of the challenge name. Publish it once; it never changes again, including when you renew.

  4. Publish a CAA record that names your authority and your account

    The record that bounds what step 3 hands us — and it is the one step here we ask you to take against us.

    The CNAME above is the whole of what a certificate authority consults for that name. That is the service: we answer the question so you do not have to. It also means that from the moment you publish it, we could ask an authority for a certificate for that name ourselves — and for *.example.com too, since a wildcard and its base share one challenge name. Every hosted responder for DNS-01 has that over the domains delegated to it. We would rather you heard it here than worked it out later.

    One record takes it back. CAA with an accounturi parameter pins issuance to a single ACME account — yours — and an order from any other account is refused by the authority itself, whatever we do:

    Both tags, because a present issuewild governs wildcard issuance instead of issue — authorising only the first leaves wildcards blocked. The record goes at the registrable name, example.com, and covers every host under it. Your account URL comes from the client you already run; with Traefik it is jq -r '.[].Account.Registration.uri' acme.json, and the console prints the same line for each of your domains with the value to substitute.

    Without this record, certificates still issue and everything works — that is the state most of the internet is in. It is simply the state in which more people than you intended could ask for one.

  5. Point your ACME client at us

    A few lines of configuration in the client you already run, and nothing to install.

    We speak the acme-dns protocol, so the clients you already run work unchanged — cert-manager, Caddy, acme.sh, lego, Traefik, Posh-ACME, Certify The Web. The console hands you a credentials file for the domain; your client publishes the challenge value through it instead of through your DNS provider's API.

    The challenge is the only part that touches us, and in every one of these it is a few lines.

    For the acme-dns clients, place the credentials file the console gives you before the client's first run. Left to themselves most of them try to register a new account, and we do not mint those — accounts and domains are created deliberately here.

    One provider line. The endpoint and credentials come from the environment.

    certificatesResolvers:
        acmealias:
          acme:
            dnsChallenge:
              provider: httpreq

      # HTTPREQ_ENDPOINT=https://api.acmealias.com/
      # HTTPREQ_USERNAME / HTTPREQ_PASSWORD = your key

  6. Request the certificate

    Your client and your certificate authority do the rest, exactly as they do today.

    Your client and your certificate authority do the rest, exactly as they do today. You can watch it happen: both commands below query the public internet, need no account and involve us only as the server answering them.

Your DNS provider keeps every other record. That CNAME delegates exactly one capability — the right to answer one name, which exists for this and nothing else. A DNS API token delegates all of them: the power to change every record you have, in order to change one.

What this is not