Guía de usuario de ACME para PKI Trust Manager

Esta guía explica cómo habilitar ACME en PKI Trust Manager e inscribir certificados con acme.sh, certbot o win-acme.

1. Cómo funciona ACME aquí#

PKI Trust Manager expone un servidor ACME RFC 8555 (parte de CertAPI). Los clientes se conectan a la URL directory de ACME, registran una cuenta con External Account Binding (EAB), crean una solicitud para un dominio y reciben el certificado emitido por su CA.

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

• EAB es obligatorio. El directory anuncia externalAccountRequired: true; el servidor no acepta cuentas sin EAB.
• La validación del dominio puede aprobarse automáticamente (RequireDomainValidation = 0 en la aplicación ACME) o exigirse mediante http-01 / dns-01.

2. Configuración del administrador: habilitar ACME en PKI Trust Manager#

Realice estos pasos una vez para cada dominio ACME (en Web Admin UI o como administrador).

1. Crear una aplicación ACME

   • Web Admin UI → Integrations → New
   • Type: ACME
   • Domain: nombre de host ACME, por ejemplo acme.secure.tron (debe coincidir con el encabezado Host que enviará el cliente; sin puerto)
   • Certificate template: seleccione una plantilla asociada a su CA (por ejemplo, Secure-WorkstationAuthentication → Secure-ISSUING-CA)
   • Require domain validation: Off para aprobar los desafíos automáticamente, On para http-01/dns-01

2. Crear un usuario/entidad ACME (EAB)

   • Web Admin UI → Users → Create → tipo ACME
   • La interfaz genera y muestra dos valores; guárdelos.
   • Key ID (KID) — por ejemplo, 58913e5c-1690-455c-9a73-834586af9daf
   • HMAC key — por ejemplo, OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk
   • Estas son las credenciales EAB del cliente (--eab-kid / --eab-hmac-key).

3. DNS

   • Dirija el FQDN de ACME al servidor PKI Trust Manager: acme.secure.tron → <server IP>

4. Enrutamiento del proxy inverso (nginx)

   • El FQDN de ACME debe dirigirse a CertAPI. Si implementó la solución con el script de instalación, añada el FQDN a los nombres ACME adicionales (EXTRA_ACME_FQDNS en .env, por ejemplo acme,acme2,acme3,acme-eab.secure.tron), vuelva a ejecutar la actualización de nginx (opción de implementación 2 — Add or Modify FQDNs), o añádalo a server_name en nginx.minimal.conf y vuelva a crear nginx.
   • Verifique: curl -k https://<acme-fqdn>/acme/directory debe devolver el directory de ACME.

5. Configuración del cliente (opcional)

   • Acme, Enabled = true para el cliente (valor predeterminado).
   • CertificatePolicy, RequireApproval = false para la emisión automática.

3. Uso del cliente#

Todos los ejemplos utilizan acme-eab.secure.tron, KID 58913e5c-1690-455c-9a73-834586af9daf y HMAC OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk. Sustitúyalos por sus propios valores.

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 en 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 nativo)#

# 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. Verificación#

# 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)

En Web Admin UI, la inscripción aparece en Certificates con el estado Issued.

5. Solución de problemas#

6. Referencia — endpoints ACME#