Intégration ACME / Let's Encrypt

Présentation

Le protocole ACME (utilisé par Let's Encrypt et d’autres autorités de certification) prend en charge le défi DNS-01 pour la validation de domaine. DNS-01 est le seul type de défi qui prend en charge les certificats wildcard (*.example.com), et il ne nécessite pas de serveur HTTP sur la machine cible.

NexDNS fournit des intégrations natives avec trois clients ACME populaires, ainsi qu’un hook CLI générique pour tout client prenant en charge les hooks DNS manuels.

Toutes les intégrations ACME nécessitent un token API avec les permissions records.read et records.write. Créez-en un sur nexdns.tech/settings/api-keys.

acme.sh

acme.sh est un client ACME en pur shell. NexDNS est pris en charge en tant que fournisseur d’API DNS intégré.

Émettre un certificat

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxx"
acme.sh --issue --dns dns_nexdns -d example.com -d '*.example.com'

Le token est enregistré dans ~/.acme.sh/account.conf après la première exécution, vous n’avez donc pas besoin de l’exporter à nouveau pour les renouvellements.

Renouveler

Les renouvellements se font automatiquement via cron. Pour forcer un renouvellement manuel :

acme.sh --renew -d example.com

Client lego / Traefik

lego est un client ACME basé sur Go qui alimente également la gestion automatique des certificats de Traefik. NexDNS est pris en charge en tant que fournisseur DNS.

Utilisation autonome

NEXDNS_API_TOKEN=nxd_xxx \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    run

Configuration Traefik

Ajoutez le résolveur de défi DNS NexDNS à votre configuration Traefik. L’exemple docker-compose.yml suivant montre une configuration typique :

services:
  traefik:
    image: traefik:v3
    command:
      - "--certificatesresolvers.nexdns.acme.dnschallenge=true"
      - "--certificatesresolvers.nexdns.acme.dnschallenge.provider=nexdns"
      - "--certificatesresolvers.nexdns.acme.email=admin@example.com"
      - "--certificatesresolvers.nexdns.acme.storage=/letsencrypt/acme.json"
    environment:
      NEXDNS_API_TOKEN: "nxd_xxxxxxxxxxxxxxxxxxxx"
    volumes:
      - letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "443:443"

volumes:
  letsencrypt:

Puis utilisez le résolveur dans les labels de votre service :

labels:
  - "traefik.http.routers.myapp.tls.certresolver=nexdns"
  - "traefik.http.routers.myapp.tls.domains[0].main=example.com"
  - "traefik.http.routers.myapp.tls.domains[0].sans=*.example.com"

Client certbot

certbot est le client officiel Let's Encrypt. Utilisez le plugin d’authentification DNS NexDNS pour la validation DNS-01 automatisée.

Installer le plugin

pip install certbot-dns-nexdns

Créer le fichier d’identifiants

Créez ~/.nexdns/certbot-credentials.ini avec votre token API :

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxx

Restreignez les permissions du fichier :

chmod 600 ~/.nexdns/certbot-credentials.ini

Émettre un certificat

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d '*.example.com'

Utilisation avec Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    certbot/dns-nexdns certonly \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d '*.example.com'

Hook CLI

Si votre client ACME prend en charge les hooks DNS manuels, vous pouvez utiliser le CLI NexDNS comme script de hook. Cela fonctionne avec tout client fournissant les options --manual-auth-hook et --manual-cleanup-hook (ex. : certbot en mode manuel).

certbot avec le hook CLI

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d '*.example.com'

Le hook lit les variables d’environnement CERTBOT_DOMAIN et CERTBOT_VALIDATION définies par certbot et crée ou supprime automatiquement l’enregistrement TXT _acme-challenge.

Le CLI doit être authentifié avant d’utiliser les hooks. Exécutez nexdns auth token nxd_xxx ou définissez la variable d’environnement NEXDNS_TOKEN.