Certificates (ACME DNS-01) through dns-gate¶
ACME clients prove control of a name with a TXT record at
_acme-challenge.<name>. dns-gate lets them write that record, and nothing else,
in any zone it manages (Route 53, EuroDNS), without a provider credential and
without a CNAME to a separate challenge server.
The gate speaks two protocols that existing clients already support:
| Endpoint | Protocol | Clients |
|---|---|---|
POST /acme/httpreq/present, POST /acme/httpreq/cleanup |
lego httpreq provider (default and RAW modes) |
lego, Traefik, certbot and win-acme hooks (a few lines of curl or PowerShell) |
POST /acme/acme-dns/update, POST /acme/acme-dns/register |
acme-dns | acme.sh dns_acmedns, the certbot acme-dns hook, certbot-dns-acmedns, cert-manager, Caddy |
Every write goes through the zone engine as the caller: the record scope of its
role, ownership by its team, the zone lock, protected records and the audit log
apply. A name and its wildcard are validated together: their values coexist in one
TXT RRset (at most acme.max_values values, 20 by default, and
acme.max_values_per_author, 4, per caller), and each value belongs to the caller
that wrote it: only that caller removes it, and nobody else can claim it
(409 value_taken). The endpoints work the same way
on AWS Lambda.
Contents:
- Choose your credential
- Set up the gate
- Recipes by platform: GitHub Actions, GitLab CI, Kubernetes, Azure, AWS
- Clients: acme.sh, certbot, lego and Traefik, win-acme, cert-manager, Caddy
- acme-dns compatibility
- Security
- Other certificate setups: static validation CNAMEs (AWS ACM), EuroDNS API clients, CNAME delegation
1. Choose your credential¶
| The ACME client runs… | Credential | Why |
|---|---|---|
| in a CI job or a workload that can fetch an OIDC token for each request (certbot or win-acme hooks) | the OIDC token, directly (Authorization: Bearer) |
Nothing to store, nothing to rotate. |
with an identity, but the client takes one fixed password for the whole run (acme.sh dns_acmedns), or the run outlives the OIDC token |
token exchange: trade the OIDC token for a gate token valid 15 minutes | Same identity and rights, a lifetime that fits the run, still nothing to store. |
| at a third party without an identity provider (hosting provider, appliance, a server outside your clouds), or in a client that reads a static secret (cert-manager, Caddy, lego) | API key | Bound to one team and one role, hashed, expiring, CIDR-bound, rotated and revoked through the API. |
OIDC tokens and gate tokens carry the identity of the job or workload: the subject is bound to a role like any other caller, and the audit log names the repository, service account or managed identity. Prefer them; API keys are the fallback for parties that have no identity provider.
The token exchange, POST /api/v1/token-exchange (RFC 8693), takes a token of an
issuer with token_exchange: true, validates it exactly as a bearer token
(signature, audience, bound_claims, bindings) and answers a token signed by the
gate with the same identity, valid 15 minutes. expires_in asks for another
lifetime, within the issuer's max_exchanged_ttl (15 minutes by default), the gate
issuer's token_ttl, and 5 minutes past the expiry of the exchanged token. Gate
tokens and API keys are never exchanged, and an exchanged token stops working if its
issuer is no longer opted in.
GATE=https://dns-gate.example.com
GATE_TOKEN=$(curl -fsS "$GATE/api/v1/token-exchange" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
--data-urlencode "subject_token=$OIDC_TOKEN" | jq -r .access_token)
2. Set up the gate¶
A role for challenges¶
roles:
acme-solver:
ephemeral_ttl: 1h # required: challenge RRsets expire and are garbage-collected
rules:
- zones: ["example.com"]
actions: [dns.read, dns.record.write]
records: { hosts: ["_acme-challenge", "_acme-challenge.**"], types: [TXT] }
ephemeral_ttlis required by the ACME endpoints (403 ephemeral_requiredotherwise): acme-dns has no cleanup call, and a client may die before its cleanup. Adding a value pushes the expiry back, never beyond the creation of the RRset pluslimits.ephemeral_lifetime_factor(4) TTLs; the reconciler deletes expired RRsets (reconcile_interval, or the Lambda maintenance schedule). A caller that also holds a permanent write role is refused: bind the ACME identity to this role only. The bound counts from the creation of the RRset: a caller that empties it and writes again starts a new one.- The record scope keeps the caller on challenge records: a leaked credential cannot touch anything else.
For OIDC tokens and the token exchange¶
Declare the issuer, opt it in to the exchange, bind the identity to the role. The
exchange needs a gate issuer (self: true) and its signing key
(DNS_GATE_TOKEN_SIGNING_KEY, see configuration).
issuers:
- name: github
issuer: https://token.actions.githubusercontent.com
audiences: [dns-gate]
token_exchange: true # off by default
- name: gate
self: true
issuer: https://dns-gate.example.com
# token_ttl: 1h # also caps exchanged tokens
bindings:
- role: acme-solver
team: web
subjects:
- issuer: github
claims: {sub: ["repo:example/certificates:ref:refs/heads/main"]}
For API keys¶
An identity holding gate.apikey.manage on the zones (and every right the key
gets) creates the key:
roles:
certificates-admin:
rules:
- zones: ["example.com"]
actions: [dns.read, dns.record.write, ui.read, gate.apikey.manage]
bindings:
- role: certificates-admin
team: web
subjects: [{issuer: github, claims: {sub: ["repo:example/dns-admin:*"]}}]
curl -fsS -H "Authorization: Bearer $TOKEN" -X POST "$GATE/api/v1/api-keys" \
-H "Content-Type: application/json" -d '{
"name": "web01 certificates", "team": "web", "role": "acme-solver",
"expires_at": "2027-06-30T00:00:00Z", "allowed_cidrs": ["192.0.2.10/32"],
"acme_domains": ["example.com", "www.example.com"]}' > key.json
The answer holds the key, shown once:
{
"id": "3f9a0c1b2d4e5f60", "team": "web", "role": "acme-solver",
"key": "dgk_3f9a0c1b2d4e5f60_q8Vx…",
"acme_dns_accounts": {
"www.example.com": {"username": "3f9a0c1b2d4e5f60", "password": "dgk_3f9a0c1b2d4e5f60_q8Vx…",
"fulldomain": "_acme-challenge.www.example.com", "subdomain": "8e5700ea-…", "allowfrom": []}
}
}
idis the user name everywhere (basic authentication, acme-dnsX-Api-User),keythe password (X-Api-Key).acme_domainscreates one acme-dns registration per domain (a wildcard shares the registration of its base name);acme_dns_accountsis, as is, the storage file of the certbot acme-dns hook, the registration file of certbot-dns-acmedns and the cert-manager secret.- Rotate before
expires_atwithPOST /api/v1/api-keys/{id}/rotate: the old key keeps working during the overlap (24h by default). Revoke withDELETE /api/v1/api-keys/{id}. See API.md.
3. Recipes by platform¶
Each recipe gets an OIDC token whose audience is the gate, then runs acme.sh with
the exchanged token and certbot with the hook
reading DNS_GATE_TOKEN. Bind the token's subject to acme-solver as in
section 2; each recipe gives the issuer
and the subject to bind. exchange is the token exchange above as a shell function,
kept for instance in scripts/exchange.sh:
exchange() {
curl -fsS "$GATE/api/v1/token-exchange" \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
--data-urlencode "subject_token=$1" | jq -r .access_token
}
Certificates issued by a job must be stored somewhere (a secret manager, a load balancer); renewals are new runs of the job, on a schedule.
GitHub Actions¶
Issuer https://token.actions.githubusercontent.com, subject
repo:<owner>/<repo>:ref:refs/heads/<branch> (or
repo:<owner>/<repo>:environment:<name> with environments).
on:
schedule: [{cron: "17 3 * * 1"}]
permissions:
id-token: write
contents: read
jobs:
certificates:
runs-on: ubuntu-latest
env:
GATE: https://dns-gate.example.com
steps:
- uses: actions/checkout@v4
- name: OIDC token for the gate
run: |
token=$(curl -fsS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=dns-gate" | jq -r .value)
echo "::add-mask::$token"
echo "OIDC_TOKEN=$token" >> "$GITHUB_ENV"
- name: acme.sh
run: |
curl -fsS https://get.acme.sh | sh -s email=ops@example.com
. scripts/exchange.sh
export ACMEDNS_BASE_URL=$GATE/acme/acme-dns ACMEDNS_USERNAME=oidc ACMEDNS_SUBDOMAIN=example.com
export ACMEDNS_PASSWORD=$(exchange "$OIDC_TOKEN")
~/.acme.sh/acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
- name: certbot
run: |
sudo apt-get install -y certbot
sudo DNS_GATE=$GATE DNS_GATE_TOKEN=$OIDC_TOKEN certbot certonly --manual \
--preferred-challenges dns --non-interactive --agree-tos -m ops@example.com \
--manual-auth-hook "$PWD/scripts/dns-gate-hook.sh" \
--manual-cleanup-hook "$PWD/scripts/dns-gate-hook.sh" -d www.example.com
GitHub tokens are short-lived: for long certbot runs, exchange the token first
(DNS_GATE_TOKEN=$(exchange "$OIDC_TOKEN")).
GitLab CI¶
Issuer https://gitlab.com (or your instance URL), subject
project_path:<group>/<project>:ref_type:branch:ref:<branch>.
certificates:
image: alpine:3.20
id_tokens:
OIDC_TOKEN:
aud: dns-gate
variables:
GATE: https://dns-gate.example.com
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
script:
- apk add --no-cache curl jq openssl certbot
- curl -fsS https://get.acme.sh | sh -s email=ops@example.com
- . scripts/exchange.sh
- export ACMEDNS_BASE_URL=$GATE/acme/acme-dns ACMEDNS_USERNAME=oidc ACMEDNS_SUBDOMAIN=example.com
- export ACMEDNS_PASSWORD=$(exchange "$OIDC_TOKEN")
- ~/.acme.sh/acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
- >
DNS_GATE=$GATE DNS_GATE_TOKEN=$OIDC_TOKEN certbot certonly --manual
--preferred-challenges dns --non-interactive --agree-tos -m ops@example.com
--manual-auth-hook "$PWD/scripts/dns-gate-hook.sh"
--manual-cleanup-hook "$PWD/scripts/dns-gate-hook.sh" -d www.example.com
Kubernetes (projected service account token)¶
Issuer: the cluster OIDC issuer (EKS: https://oidc.eks.<region>.amazonaws.com/id/<id>;
any cluster: kubectl get --raw /.well-known/openid-configuration), subject
system:serviceaccount:<namespace>:<service account>. A CronJob mounts a token for
the gate audience; kubelet renews the file.
apiVersion: batch/v1
kind: CronJob
metadata: {name: certificates, namespace: certificates}
spec:
schedule: "17 3 * * 1"
jobTemplate:
spec:
template:
spec:
serviceAccountName: certificates
restartPolicy: Never
containers:
- name: acme
image: registry.example.com/acme-tools:1.0 # acme.sh, certbot, curl, jq, the scripts
env:
- {name: GATE, value: https://dns-gate.example.com}
command: ["/bin/sh", "-ec"]
args:
- |
. /scripts/exchange.sh
OIDC_TOKEN=$(cat /var/run/secrets/dns-gate/token)
ACMEDNS_BASE_URL=$GATE/acme/acme-dns ACMEDNS_USERNAME=oidc ACMEDNS_SUBDOMAIN=example.com \
ACMEDNS_PASSWORD=$(exchange "$OIDC_TOKEN") \
acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
DNS_GATE=$GATE DNS_GATE_TOKEN=$OIDC_TOKEN certbot certonly --manual \
--preferred-challenges dns --non-interactive --agree-tos -m ops@example.com \
--manual-auth-hook /scripts/dns-gate-hook.sh --manual-cleanup-hook /scripts/dns-gate-hook.sh \
-d www.example.com
volumeMounts:
- {name: dns-gate-token, mountPath: /var/run/secrets/dns-gate, readOnly: true}
volumes:
- name: dns-gate-token
projected:
sources:
- serviceAccountToken: {path: token, audience: dns-gate, expirationSeconds: 3600}
In a cluster, cert-manager is usually the better client; its acmeDNS solver reads a static secret, so it uses an API key.
Azure (managed identity, AKS workload identity)¶
Issuer https://login.microsoftonline.com/<tenant-id>/v2.0, configured as in
configuration; bind on the oid of the managed identity. The
token audience is the gate app registration (api://dns-gate).
# VM, App Service, Container Apps, Functions (managed identity)
OIDC_TOKEN=$(curl -fsS -H Metadata:true \
"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://dns-gate" \
| jq -r .access_token)
# AKS workload identity, Azure DevOps (workload identity federation), any az login
OIDC_TOKEN=$(az account get-access-token --scope api://dns-gate/.default --query accessToken -o tsv)
ACMEDNS_BASE_URL=$GATE/acme/acme-dns ACMEDNS_USERNAME=oidc ACMEDNS_SUBDOMAIN=example.com \
ACMEDNS_PASSWORD=$(exchange "$OIDC_TOKEN") \
acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
DNS_GATE=$GATE DNS_GATE_TOKEN=$OIDC_TOKEN certbot certonly --manual --preferred-challenges dns \
--manual-auth-hook /etc/letsencrypt/dns-gate-hook.sh --manual-cleanup-hook /etc/letsencrypt/dns-gate-hook.sh \
-d www.example.com
On Windows servers with a managed identity, the win-acme script fetches the token the same way.
AWS (outbound identity federation)¶
IAM outbound identity federation signs tokens for the calling role
(sts:GetWebIdentityToken), from EC2, ECS, Lambda, CodeBuild: anything with an IAM
role allowed that action. Issuer: the URL given by
aws iam get-outbound-web-identity-federation-info; subject: the role ARN.
issuers:
- name: aws
issuer: https://<id>.tokens.sts.global.api.aws # from get-outbound-web-identity-federation-info
audiences: [dns-gate]
token_exchange: true
bindings:
- role: acme-solver
team: web
subjects: [{issuer: aws, claims: {sub: ["arn:aws:iam::111122223333:role/certificates"]}}]
OIDC_TOKEN=$(aws sts get-web-identity-token --audience dns-gate --signing-algorithm ES384 \
--query WebIdentityToken --output text)
ACMEDNS_BASE_URL=$GATE/acme/acme-dns ACMEDNS_USERNAME=oidc ACMEDNS_SUBDOMAIN=example.com \
ACMEDNS_PASSWORD=$(exchange "$OIDC_TOKEN") \
acme.sh --issue --dns dns_acmedns -d example.com -d '*.example.com'
DNS_GATE=$GATE DNS_GATE_TOKEN=$OIDC_TOKEN certbot certonly --manual --preferred-challenges dns \
--manual-auth-hook /etc/letsencrypt/dns-gate-hook.sh --manual-cleanup-hook /etc/letsencrypt/dns-gate-hook.sh \
-d www.example.com
4. Clients¶
acme.sh¶
The built-in dns_acmedns sends POST $ACMEDNS_BASE_URL/update with
X-Api-User: $ACMEDNS_USERNAME, X-Api-Key: $ACMEDNS_PASSWORD and
{"subdomain":"$ACMEDNS_SUBDOMAIN", "txt": "<value>"}, and checks that the answer
contains the value.
| Variable | With a token | With an API key |
|---|---|---|
ACMEDNS_BASE_URL |
https://dns-gate.example.com/acme/acme-dns |
same |
ACMEDNS_USERNAME |
any non-empty value, e.g. oidc |
the key id |
ACMEDNS_PASSWORD |
the exchanged gate token (or an OIDC token that outlives the run) | the key |
ACMEDNS_SUBDOMAIN |
the domain of the certificate (example.com) |
the domain, or its registration from acme_dns_accounts |
dns_acmednssends one subdomain for every name of a certificate. As with acme-dns, a certificate covers one name and its wildcard (both use_acme-challenge.<name>); issue one certificate per other name.- The gate keeps the two most recent values per subdomain, as acme-dns does (per
subject and domain with a token): enough for a name and its wildcard. acme.sh has
no cleanup for acme-dns; the RRset expires with the role's
ephemeral_ttl. - Always set
ACMEDNS_USERNAMEandACMEDNS_PASSWORD: without them acme.sh tries an anonymous/register, which the gate refuses. - acme.sh saves the variables in the domain configuration. With an API key,
renewals (
acme.sh --cron) need nothing else; with a token, set them again at each run, the saved token having expired.
certbot¶
Hooks with curl (tokens and API keys)¶
One script serves as --manual-auth-hook and --manual-cleanup-hook (certbot sets
CERTBOT_AUTH_OUTPUT for the cleanup only). It sends DNS_GATE_TOKEN when set,
else the API key of /etc/letsencrypt/dns-gate.env (mode 600: DNS_GATE,
DNS_GATE_KEY_ID, DNS_GATE_KEY). Save it as dns-gate-hook.sh (mode 700):
#!/bin/sh
set -eu
[ -f /etc/letsencrypt/dns-gate.env ] && . /etc/letsencrypt/dns-gate.env
action=present
[ -n "${CERTBOT_AUTH_OUTPUT+x}" ] && action=cleanup
if [ -n "${DNS_GATE_TOKEN:-}" ]; then
auth="Authorization: Bearer $DNS_GATE_TOKEN"
else
auth="Authorization: Basic $(printf %s "$DNS_GATE_KEY_ID:$DNS_GATE_KEY" | base64 | tr -d '\n')"
fi
curl -fsS -H "$auth" -H "Content-Type: application/json" \
-d "{\"fqdn\": \"_acme-challenge.${CERTBOT_DOMAIN#\*.}.\", \"value\": \"$CERTBOT_VALIDATION\"}" \
"$DNS_GATE/acme/httpreq/$action" > /dev/null
if [ "$action" = present ]; then sleep "${DNS_GATE_PROPAGATION:-30}"; fi
certbot certonly --manual --preferred-challenges dns \
--manual-auth-hook /etc/letsencrypt/dns-gate-hook.sh \
--manual-cleanup-hook /etc/letsencrypt/dns-gate-hook.sh \
-d example.com -d '*.example.com' -d www.example.com
The sleep leaves the provider time to serve the record on its name servers
(Route 53 is usually in sync within a minute). certbot renew reuses the hooks.
The acme-dns hook (API keys)¶
The hook acme-dns-auth.py
reads the account of each domain from a storage file and calls /update; it calls
/register only for a domain without account, which the gate refuses
(401 registration_requires_api_key). Seed the storage file from the key:
- Install the hook (python3 and requests) and set its constants:
ACMEDNS_URL = "https://dns-gate.example.com/acme/acme-dns",STORAGE_PATH = "/etc/letsencrypt/acmedns.json". - Create the key with every domain in
acme_domains, thenjq '.acme_dns_accounts' key.json > /etc/letsencrypt/acmedns.json(mode 600). - Run
certbot certonly --manual --preferred-challenges dns --manual-auth-hook /etc/letsencrypt/acme-dns-auth.py -d example.com -d '*.example.com'. There is no CNAME to create. - After a rotation, write the new
acme_dns_accountsto the storage file.
To add a domain, add it to the key's acme_domains (PUT /api/v1/api-keys/{id})
and copy its subdomain from GET /api/v1/api-keys/{id}, or add an entry whose
subdomain is the domain itself, which needs no registration:
"api.example.com": {"username": "3f9a0c1b2d4e5f60", "password": "dgk_…",
"fulldomain": "_acme-challenge.api.example.com", "subdomain": "api.example.com", "allowfrom": []}
certbot-dns-acmedns (API keys)¶
The certbot-dns-acmedns plugin reads the same storage file:
# /etc/letsencrypt/acmedns.ini (mode 600)
dns_acmedns_api_url = https://dns-gate.example.com/acme/acme-dns
dns_acmedns_registration_file = /etc/letsencrypt/acmedns.json
certbot certonly -a dns-acmedns --dns-acmedns-credentials /etc/letsencrypt/acmedns.ini \
--dns-acmedns-propagation-seconds 30 -d example.com -d '*.example.com'
lego and Traefik¶
HTTPREQ_ENDPOINT=https://dns-gate.example.com/acme/httpreq \
HTTPREQ_USERNAME=3f9a0c1b2d4e5f60 HTTPREQ_PASSWORD='dgk_3f9a0c1b2d4e5f60_q8Vx…' \
lego --email ops@example.com --dns httpreq -d example.com -d '*.example.com' run
lego's httpreq provider sends basic authentication only, hence an API key.
HTTPREQ_MODE=RAW also works: the gate computes the TXT value from keyAuth.
Traefik embeds lego: give it the same variables and
certificatesResolvers.<name>.acme.dnsChallenge.provider=httpreq.
win-acme¶
win-acme's script validation calls a PowerShell script to create and delete the
record. C:\ProgramData\dns-gate\dns-gate.ps1, with an API key:
param([string]$Action, [string]$RecordName, [string]$Token)
$ErrorActionPreference = 'Stop'
$id = (Get-Content 'C:\ProgramData\dns-gate\key-id.txt' -Raw).Trim()
$key = (Get-Content 'C:\ProgramData\dns-gate\key.txt' -Raw).Trim()
$auth = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("${id}:${key}"))
$body = @{ fqdn = "$RecordName."; value = $Token } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://dns-gate.example.com/acme/httpreq/$Action" `
-Headers @{ Authorization = $auth } -ContentType 'application/json' -Body $body | Out-Null
if ($Action -eq 'present') { Start-Sleep -Seconds 30 }
Restrict the key files to Administrators and SYSTEM. On an Azure VM with a managed identity, use a token instead of the key files:
$mi = 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://dns-gate'
$auth = 'Bearer ' + (Invoke-RestMethod -Headers @{ Metadata = 'true' } -Uri $mi).access_token
wacs.exe --source manual --host example.com,*.example.com ^
--validationmode dns-01 --validation script ^
--dnscreatescript C:\ProgramData\dns-gate\dns-gate.ps1 --dnscreatescriptarguments "present {RecordName} {Token}" ^
--dnsdeletescript C:\ProgramData\dns-gate\dns-gate.ps1 --dnsdeletescriptarguments "cleanup {RecordName} {Token}"
win-acme's own acme-dns plugin registers anonymously and expects a CNAME: use the script validation instead.
cert-manager¶
cert-manager's acmeDNS solver reads its accounts from a secret, hence an API key:
jq '.acme_dns_accounts' key.json > acmedns.json
kubectl -n cert-manager create secret generic dns-gate-acme-dns --from-file=acmedns.json
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
privateKeySecretRef: {name: letsencrypt-account}
solvers:
- dns01:
acmeDNS:
host: https://dns-gate.example.com/acme/acme-dns
accountSecretRef: {name: dns-gate-acme-dns, key: acmedns.json}
Caddy¶
With the caddy-dns/acmedns module and an API key:
example.com {
tls {
dns acmedns {
username 3f9a0c1b2d4e5f60
password {env.DNS_GATE_KEY}
subdomain example.com
server_url https://dns-gate.example.com/acme/acme-dns
}
}
}
5. acme-dns compatibility¶
| acme-dns | Through the gate |
|---|---|
_acme-challenge.<name> CNAME to <subdomain>.<acme-dns zone> |
No CNAME: the gate writes _acme-challenge.<domain> in its zone. fulldomain is that record. |
subdomain is a registration UUID |
A registration of an API key, or the domain name itself (the only form with a token). |
X-Api-User / X-Api-Key |
Key id / key, or any value / a token. They win over basic authentication when both are sent (python requests sends basic authentication taken from the URL). Authorization: Bearer also works. |
/register creates an anonymous account |
401 registration_requires_api_key. With an API key (basic authentication, e.g. https://<id>:<key>@dns-gate.example.com/acme/acme-dns, or X-Api-User/X-Api-Key), {"domain": "<name>", "allowfrom": [...]} (domain is a gate extension) answers 201 with an account whose password is the key. Tokens cannot register (403). |
| Two most recent TXT values per subdomain | Same, per registration (per subject and domain with a token). Values written by other means (httpreq) are left alone. Registrations and their values are saved only once the record is written. |
| No cleanup | Same; the RRset expires with the role's ephemeral_ttl. |
allowfrom per registration |
Stricter: for a key and a domain, the address must be allowed by every registration of that key for that domain that has an allowfrom, for every write of the key to the _acme-challenge RRset of that domain: acme-dns whatever the subdomain used, httpreq, the RRset API and the EuroDNS-compatible API. On top of the key's allowed_cidrs. |
| Unlimited registrations | At most acme.max_registrations (100) per key or token subject (409 too_many_registrations); those of token subjects are purged after acme.registration_idle (30 days) without use. |
Errors {"error": "..."} |
Same, with a message: bad_subdomain, bad_txt, forbidden, ephemeral_required… |
The unmodified acme.sh dns_acmedns (with an API key, an exchanged token and an
OIDC token) and certbot acme-dns hook run against the gate in CI, at pinned versions.
6. Security¶
- Prefer tokens: nothing to store or rotate, and the audit log names the repository, service account or role. An exchanged token lasts 15 minutes at most by default, never much longer than the token it replaces, and only the issuers you opt in can be exchanged.
- An API key is a bearer secret: store it like a password (mode 600 files,
Kubernetes secrets, the Windows key files above). The gate keeps only its
SHA-256, compares it in constant time and never logs it. Give each server its own
key, with
allowed_cidrsandexpires_at; revoke it withDELETE /api/v1/api-keys/{id}. - Whatever the credential, the role limits it to
_acme-challengeTXT records of the zones you list: enough to obtain certificates for those names, nothing else. - Value ownership (
value_taken, cleanup of one's own values) and the per-author and per-RRset caps apply to the/acmeendpoints. The RRset itself is owned by a team: any identity of the same team whose role covers_acme-challengeTXT can still rewrite it through the RRset API or the EuroDNS-compatible API. Give each third party its own team. A key never outgrows its issuer (rights, ephemeral TTL, change limit), and stops working if its role later grants more than at issuance (403 role_widened). - Exchanges (
gate.token.exchange), refused API keys (apikey.authenticate; unknown or malformed keys are counted per address and minute) and every write are in the audit log, with the subject, team and record.
7. Other certificate setups¶
Static validation CNAMEs (AWS ACM)¶
AWS ACM (and other CAs using DNS validation with a fixed token) validates through a CNAME that does not change between renewals: create it with the Terraform provider, in the same stack as the certificate.
resource "aws_acm_certificate" "www" {
domain_name = "www.example.com"
validation_method = "DNS"
}
resource "dnsgate_record_set" "www_validation" {
for_each = {
for o in aws_acm_certificate.www.domain_validation_options : o.domain_name => o
}
zone = "example.com"
name = trimsuffix(each.value.resource_record_name, ".example.com.")
type = each.value.resource_record_type
ttl = 600
values = [each.value.resource_record_value]
}
resource "aws_acm_certificate_validation" "www" {
certificate_arn = aws_acm_certificate.www.arn
validation_record_fqdns = [for o in aws_acm_certificate.www.domain_validation_options : o.resource_record_name]
depends_on = [dnsgate_record_set.www_validation]
}
A role allowing CNAME on _* and _*.** hosts is enough. ACM validates through
public DNS: the CNAME must be in the public zone.
EuroDNS API clients¶
Clients of the EuroDNS API with a configurable base URL can use the
EuroDNS-compatible API of the gate, for EuroDNS zones only, with an API key
(X-App-Id: <key id>, X-Api-Key: <key>) or a static virtual key. Clients that
read the zone, add a TXT and save the whole zone (Caddy with EuroDNS/libdns-eurodns)
need rebase_on_save: true on their role: only the TXT change is applied on top of
the current zone, anything else they send back is ignored instead of refused.
Prefer the endpoints above: they work on every provider.
Delegating _acme-challenge with a CNAME¶
When renewals must not touch the main zone at all, point
_acme-challenge.www.example.com to a zone dedicated to challenges (a Route 53 zone
with a narrow IAM policy, an acme-dns server, or a zone behind the gate). The CNAME
is created once, through Terraform or the gate; ACME CAs follow it, cert-manager
with cnameStrategy: Follow, lego natively.