Setting Up ACME¶

This guide covers creating an ACME server configuration, provisioning an account with domain bindings, and connecting an ACME client.

For an overview of ACME and how it compares to Couriers, see ACME — Introduction.

Prerequisites¶

Before you begin, ensure the following:

You are signed in to the Zaita web portal with the Deployment Administrator or Super Administrator role.
You have at least one intermediate certificate configured in your PKI that will be used to sign ACME-issued certificates.
The domains you want to issue certificates for are registered under Admin → Domains.

Step 1 — Create an ACME Server Configuration¶

Each ACME server configuration provides an independent ACME endpoint with its own URL namespace, signing certificate, and settings.

Navigate to Admin → ACME Servers in the web portal.
Select Add ACME Server.
Configure the following settings:

Setting	Description
Name	A descriptive name for this ACME server (e.g., `Production ACME` or `Dev Environment`)
Description	Optional description for documentation purposes
Status	Set to Active to enable the endpoint; Inactive to disable it
Intermediate Certificate	The PKI intermediate certificate that will sign issued certificates
Require EAB	Enable to require External Account Binding for account registration (recommended)
Default Validity (days)	Default certificate lifetime if not specified by the client (1–825 days)
Maximum Validity (days)	Maximum certificate lifetime regardless of client request
Default Algorithm	Key algorithm for server-specified fields (e.g., `ec-384`, `rsa-4096`)
Default Digest	Digest algorithm (e.g., `sha256`, `sha384`, `sha512`)

Optionally configure additional metadata:
Terms of Service URL — URL to your organisation's certificate terms of service
Website URL — URL to documentation or support information
CAA Identities — CAA record identities for the directory response
Save the configuration.

Once saved, the server's Directory URL is displayed. This is the URL you will provide to ACME clients:

https://your-region.zaita.com/acme/{server-uuid}/directory

Step 2 — Create an ACME Account¶

ACME accounts must be pre-provisioned in the platform before clients can register. Each account is associated with specific domain bindings that control which certificates it can request.

Navigate to Admin → ACME Servers and select your server configuration.
Select the Accounts tab, then Add Account.
Enter a descriptive name (e.g., web-server-prod-01).
Configure domain bindings — these determine which domains the account can request certificates for:

Binding Option	Effect
Exact domain	Account can request certificates for exactly this domain
Allow subdomains	Account can request certificates for any subdomain (e.g., `*.example.com` binding allows `app.example.com`)
Allow wildcard	Account can request wildcard certificates (e.g., `*.example.com`)

Save the account.

Generate EAB Credentials¶

If the server requires External Account Binding (recommended), generate credentials for the account:

From the account view, select Generate EAB Credentials.
The platform generates:
Key ID (kid) — A unique identifier
HMAC Key — A shared secret for signing the registration request
Copy these credentials immediately. The HMAC key is displayed only once and cannot be retrieved later. If lost, you must generate new credentials.

Step 3 — Configure Your ACME Client¶

Configure your ACME client to use the Zaita ACME server. The exact configuration varies by client, but all require:

Directory URL — The ACME server's directory endpoint
EAB credentials — The Key ID and HMAC key generated in Step 2

Certbot¶

certbot certonly \
  --server https://your-region.zaita.com/acme/{server-uuid}/directory \
  --eab-kid "YOUR_KEY_ID" \
  --eab-hmac-key "YOUR_HMAC_KEY" \
  --domain example.com \
  --standalone

For automated renewals, store the credentials and configure Certbot's renewal hooks as needed.

acme.sh¶

# Register account with EAB
acme.sh --register-account \
  --server https://your-region.zaita.com/acme/{server-uuid}/directory \
  --eab-kid "YOUR_KEY_ID" \
  --eab-hmac-key "YOUR_HMAC_KEY"

# Issue certificate
acme.sh --issue \
  --server https://your-region.zaita.com/acme/{server-uuid}/directory \
  -d example.com \
  --standalone

Caddy¶

In your Caddyfile:

{
  acme_ca https://your-region.zaita.com/acme/{server-uuid}/directory
  acme_eab {
    key_id YOUR_KEY_ID
    mac_key YOUR_HMAC_KEY
  }
}

example.com {
  respond "Hello, world!"
}

Traefik¶

In your Traefik static configuration:

certificatesResolvers:
  zaita:
    acme:
      caServer: https://your-region.zaita.com/acme/{server-uuid}/directory
      email: [email protected]
      storage: /etc/traefik/acme.json
      eab:
        kid: YOUR_KEY_ID
        hmacEncoded: YOUR_HMAC_KEY

cert-manager (Kubernetes)¶

Create an ACME ClusterIssuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: zaita-acme
spec:
  acme:
    server: https://your-region.zaita.com/acme/{server-uuid}/directory
    privateKeySecretRef:
      name: zaita-acme-account-key
    externalAccountBinding:
      keyID: YOUR_KEY_ID
      keySecretRef:
        name: zaita-eab-secret
        key: hmac-key
      keyAlgorithm: HS256

Create the EAB secret:

apiVersion: v1
kind: Secret
metadata:
  name: zaita-eab-secret
type: Opaque
stringData:
  hmac-key: YOUR_HMAC_KEY

Step 4 — Test Certificate Issuance¶

Run your ACME client to request a test certificate. A successful request will:

Create an account (first request only)
Submit an order for the requested domains
Receive instant authorisations (no challenge-response required)
Generate a CSR and submit it to the finalize endpoint
Poll until the certificate is ready
Download the certificate chain

The issued certificate will be signed by the intermediate certificate you configured on the ACME server.

Verify the Certificate Chain¶

After obtaining a certificate, verify the chain:

openssl verify -CAfile /path/to/root-ca.pem -untrusted /path/to/intermediate.pem /path/to/cert.pem

Troubleshooting¶

"Account does not exist" Error¶

The EAB credentials may be incorrect or already used. Check that: - The Key ID matches exactly (case-sensitive) - The HMAC key is base64url-encoded (not standard base64) - The credentials have not already been consumed by a previous registration

"Unauthorized" Error on Order Creation¶

The account does not have a domain binding for one or more requested domains. Check the account's domain bindings in the platform UI.

Certificate Not Ready After Finalize¶

The order may still be processing. Poll the order endpoint until the status changes to valid or invalid. If the order becomes invalid, check the error response for details.

Connection Refused¶

Verify: - The ACME server configuration is set to Active - The directory URL is correct - Network connectivity to the Zaita platform is available

Next Steps¶

Managing ACME Servers — Modify server settings and view issued certificates
Managing Accounts — Update domain bindings and regenerate EAB credentials
Best Practices — Security and operational recommendations