Guide utilisateur ACME pour PKI Trust Manager

Ce guide explique comment activer ACME dans PKI Trust Manager et inscrire des certificats à l’aide de acme.sh, certbot ou win-acme.

1. Fonctionnement d’ACME ici#

PKI Trust Manager expose un serveur ACME RFC 8555 (composant de CertAPI). Les clients se connectent à l’URL directory ACME, créent un compte avec External Account Binding (EAB), commandent un certificat pour un domaine et reçoivent le certificat émis par votre CA.

ACME client ──https──▶ https://<acme-fqdn>/acme/directory (nginx → CertAPI)
 │ account (EAB) → order → finalize
 ▼
CAProxy(ca.ApiUrl) → caapi → ADCS → certificate

• EAB est obligatoire. Le directory annonce externalAccountRequired: true ; le serveur n’accepte pas les comptes sans EAB.
• La validation du domaine peut être automatiquement validée (RequireDomainValidation = 0 dans l’application ACME) ou imposée via http-01 / dns-01.

2. Configuration administrateur — activer ACME dans PKI Trust Manager#

Effectuez ces étapes une fois pour chaque domaine ACME (dans Web Admin UI ou en tant qu’administrateur).

1. Créer une application ACME

   • Web Admin UI → Integrations → New
   • Type : ACME
   • Domain : nom d’hôte ACME, par exemple acme.secure.tron (doit correspondre à l’en-tête Host envoyé par le client, sans port)
   • Certificate template : choisissez un modèle associé à votre CA (par exemple Secure-WorkstationAuthentication → Secure-ISSUING-CA)
   • Require domain validation : Off pour valider automatiquement les défis, On pour http-01/dns-01

2. Créer un utilisateur/une entité ACME (EAB)

   • Web Admin UI → Users → Create → type ACME
   • L’interface génère et affiche deux valeurs : enregistrez-les.
   • Key ID (KID) — par exemple 58913e5c-1690-455c-9a73-834586af9daf
   • HMAC key — par exemple OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk
   • Ce sont les identifiants EAB client (--eab-kid / --eab-hmac-key).

3. DNS

   • Faites pointer le FQDN ACME vers le serveur PKI Trust Manager : acme.secure.tron → <server IP>

4. Routage du reverse proxy (nginx)

   • Le FQDN ACME doit être routé vers CertAPI. Si le déploiement utilise le script d’installation, ajoutez le FQDN aux entrées ACME supplémentaires (EXTRA_ACME_FQDNS dans .env, par exemple acme,acme2,acme3,acme-eab.secure.tron), relancez la mise à jour nginx (option de déploiement 2 — Add or Modify FQDNs), ou ajoutez-le à nginx.minimal.conf server_name puis recréez nginx.
   • Vérification : curl -k https://<acme-fqdn>/acme/directory doit renvoyer le directory ACME.

5. Paramètres client (facultatif)

   • Acme, Enabled = true pour le client (valeur par défaut).
   • CertificatePolicy, RequireApproval = false pour l’émission automatique.

3. Utilisation côté client#

Tous les exemples utilisent acme-eab.secure.tron, KID 58913e5c-1690-455c-9a73-834586af9daf et HMAC OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk. Remplacez-les par vos propres valeurs.

3a. acme.sh (Linux / macOS / Windows Git Bash)#

# install (one time)
curl https://get.acme.sh | sh
 
# issue (use http:// directory URL for lab setups with self-signed cert;
# directory advertises http:// URLs anyway)
~/.acme.sh/acme.sh --issue \
  --server http://acme-eab.secure.tron/acme/directory \
  -d acme-eab.secure.tron \
  --eab-kid 58913e5c-1690-455c-9a73-834586af9daf \
  --eab-hmac-key 'OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk' \
  --webroot /tmp/acme-webroot \
  --keylength 2048 \
  --force
 
# certificates land in ~/.acme.sh/acme-eab.secure.tron/
# renew (acme.sh installs cron/task automatically; or run --renew manually)
~/.acme.sh/acme.sh --renew -d acme-eab.secure.tron --force

3b. certbot (Linux / macOS / WSL2 sur Windows)#

# install: Debian/Ubuntu
sudo apt-get install -y certbot
# macOS: brew install certbot
# Windows: use WSL2 (certbot has no native Windows support)
 
# LAB ONLY — trust PKI Trust Manager self-signed cert (certbot verifies TLS
# and has no insecure flag). Not needed with real certificate.
sudo cp /opt/pki-trust-manager/certs/cert.crt /usr/local/share/ca-certificates/pki-tm.crt
sudo update-ca-certificates
 
# issue (EAB + RSA 2048 are required — certbot defaults to ECDSA, which
# ADCS template rejects)
sudo certbot certonly --manual --preferred-challenges http \
  --server https://acme-eab.secure.tron/acme/directory \
  -d acme-eab.secure.tron \
  --eab-kid 58913e5c-1690-455c-9a73-834586af9daf \
  --eab-hmac-key 'OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk' \
  --key-type rsa --rsa-key-size 2048 \
  --manual-auth-hook 'true' \
  --agree-tos -m [email protected] -n
 
# certificates land in /etc/letsencrypt/live/acme-eab.secure.tron/
# (certbot installs automatic renewal task)

3c. win-acme (Windows natif)#

# download + extract win-acme (no installer):
# https://github.com/win-acme/win-acme/releases (win-acme.v2.2.9.1701.x64.trimmed.zip)
 
# LAB ONLY — trust PKI Trust Manager self-signed cert in Windows store:
Import-Certificate -FilePath cert.crt -CertStoreLocation Cert:\CurrentUser\Root
 
# issue (filesystem validation avoids needing admin; server auto-passes)
.\wacs.exe --source manual --host acme-eab.secure.tron `
  --baseuri https://acme-eab.secure.tron/acme/directory `
  --eab-key-identifier 58913e5c-1690-455c-9a73-834586af9daf `
  --eab-key OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk `
  --validation filesystem --webroot C:\certs\acmewebroot `
  --store pemfiles --pemfilespath C:\certs `
  --accepttos --emailaddress [email protected] --notaskscheduler
 
# certificates exported to C:\certs\ (acme-eab.secure.tron-crt.pem, -key.pem, -chain.pem)

4. Vérification#

# issued certificate
openssl x509 -in <cert-file> -noout -subject -issuer -dates -ext subjectAltName
# expect: CN/SAN = your ACME domain, issuer = your CA (e.g. Secure-ISSUING-CA)

Dans Web Admin UI, l’inscription apparaît dans Certificates avec le statut Issued.

5. Dépannage#

6. Référence — endpoints ACME#