Skip to content

Issuing a Certificate via Let's Encrypt

This guide walks through issuing a publicly-trusted certificate using Let's Encrypt as the Certificate Authority, obtained through Zaita's own ACME server using certbot and External Account Binding (EAB).

Two separate Let's Encrypt-related pieces work together to make this possible:

  • The Let's Encrypt Certificate Authority integration — Zaita acts as an ACME client against the real Let's Encrypt service, proving domain ownership via a DNS CNAME delegated to Zaita.
  • Zaita's own ACME server — this is the endpoint your certbot client actually talks to. It authenticates clients using EAB and, when backed by the Let's Encrypt integration, forwards issuance to the real Let's Encrypt CA.

Running certbot against Zaita's ACME server (rather than directly against Let's Encrypt) lets you keep certificate policy, auditing, and key custody inside Zaita while still getting a publicly-trusted certificate.

Prerequisites

  • You are signed in to the Zaita web portal with the Super Administrator or Deployment Administrator role.
  • You can create DNS records (TXT and CNAME) for the domain you want to issue certificates for.
  • certbot is installed on the machine that will request the certificate.

Step 1 — Add the Let's Encrypt Certificate Authority

  1. Navigate to Integrations → Certificate Authorities.
  2. Select Add Certificate Authority.
  3. Choose Let's Encrypt as the type and configure:
Field Description
Environment Staging issues untrusted certificates but has far higher rate limits — use it to prove out your CNAME delegation before switching to Production.
Account Contact Email Contact email registered with Let's Encrypt for expiry and policy notices.
  1. Save the integration.

Step 2 — Add your domain and set Let's Encrypt as the default CA

  1. Navigate to Admin → Domains.
  2. If the domain isn't listed yet, select Add Domain and enter it. If it already exists, open it instead.
  3. Set Default Certificate Authority to the Let's Encrypt integration you created in Step 1, and save.

Step 3 — Verify the domain

Public domains must prove ownership before Let's Encrypt (or any publicly-trusted CA) can issue for them. Similarly, Zaita requires proof that you have control over a public domain before it will attempt to provision a certificate on your behalf.

  1. On the domain's page, note the validation record Zaita shows you:
  2. Host: _zaita-domain-verification.<your-domain>
  3. Type: TXT
  4. Value: zaita-domain-verification=<validation-token> (the token shown on the page). If no token is shown click Regenerate Token
  5. Create that TXT record with your DNS provider.
  6. Back on the domain's page, select Validate Now. Zaita queries DNS and marks the domain validated once the record is found with a matching value.

DNS propagation can take a few minutes — if validation fails immediately after creating the record, wait and retry. You can see the result of the validation test in the Audit Logs

Step 4 — Add the CNAME Delegation

Let's Encrypt validates ownership with a DNS-01 challenge. Rather than you publishing per-order challenge records yourself, you delegate the challenge name to Zaita once, and Zaita answers every future challenge on your behalf.

  1. Navigate to Admin → Domains → CNAME Delegation.
  2. Add an entry for the exact name you intend to issue certificates for (e.g. example.com, or *.example.com for a wildcard).

!!! note "Subdomains need their own delegation entry" Let's Encrypt forces coverage to be exact, not inherited. Delegating example.com does not cover www.example.com — Let's Encrypt validates each identifier at its own challenge name (_acme-challenge.www.example.com), which is a different name than the one you delegated. The only exception is a wildcard (*.example.com), which validates at the base domain's challenge name and so shares its delegation. To issue for a subdomain, add that subdomain as its own CNAME Delegation entry — it does not need to be registered as a separate Domain.

Step 5 — Verify the CNAME Delegation

  1. On the CNAME Delegation page, each entry shows the record you need to create:
  2. Host: _acme-challenge.<your-delegated-name>
  3. Type: CNAME
  4. Target: _acme-challenge.<name>.auth.<zaita-acme-dns-zone> (shown in full on the page)
  5. Create that CNAME record with your DNS provider.
  6. Select Verify on the entry. Zaita queries DNS and marks the entry verified once the CNAME resolves to the expected target.

A delegation entry that later fails a re-check (for example, due to a transient DNS outage) is marked unverified again and will block issuance until it is re-verified — the Last Checked time next to each entry shows how current its status is.

Step 6 — Add an ACME server with EAB

Zaita's ACME server capability provides External Account Binding (account based authentication) using the protocols built in KID/HMAC approach. All modern ACME clients (e.g., lego, certbot, winacme, acme.sh) support external account binding as part of their ACME RFC8555 implementation.

  1. Navigate to ACME Servers and select Add ACME Server.
  2. Configure the server:
  3. Name / Description — anything identifiable, e.g. Let's Encrypt via Zaita.
  4. Status — Active.
  5. Use domain default CA — Leave enabled if you want Zaita to auto bind the certificate authority based on domain name used by requestor; OR:
  6. Certificate Authority Source — choose Integration, then select the Let's Encrypt integration from Step 1.
  7. Require EAB — enabled (this is the default, and required for this flow).
  8. Leave the validity, algorithm, and rate-limit fields at their defaults unless you have specific requirements — see Setting up ACME for the full field reference.
  9. Save the server. Note the ACME Directory URL. This will be needed in step 7.
  10. On the new server's page, go to Accounts → Add Account.
  11. Enter the authorised FQDNs this account may request certificates for (one per line; supports *.example.com wildcards) and an optional contact email, then save.
  12. Zaita generates and displays the account's EAB credentials once:
  13. Key ID (eab_kid)
  14. HMAC Key (eab_hmac_key)

Copy both now — the HMAC key cannot be retrieved again after you leave this page.

Step 7 — Issue the certificate with certbot

On the machine that needs the certificate, run certbot against your Zaita ACME server's directory URL, supplying the EAB credentials from Step 6:

certbot certonly \
  --server <acme-directory-url> \
  --eab-kid <key-id> \
  --eab-hmac-key <hmac-key> \
  --preferred-challenges dns \
  -d example.com

The ACME Directory URL is shown on its page in the Zaita portal. Certbot registers the EAB-bound account, places an order, and Zaita fulfills it against Let's Encrypt using the CNAME delegation you verified in Step 5 — no further DNS work is required for this or future orders on the same name.

Troubleshooting and next steps

  • Order fails at DNS-01 validation — confirm the identifier you requested matches a verified CNAME Delegation entry exactly (see the note in Step 4).
  • Domain shows as unvalidated — re-check the TXT record from Step 3 is still present; it is only queried once, at validation time, but a since-removed record will fail re-validation.
  • For the full set of ACME server options, other supported clients, and general troubleshooting, see Introduction to ACME and Setting up ACME.