PKI Trust Manager ACME 用户指南

在 PKI Trust Manager 中启用 ACME，并使用 acme.sh、certbot 或 win-acme 注册证书。

本指南介绍如何在 PKI Trust Manager 中启用 ACME，并使用 acme.sh、certbot 或 win-acme 注册证书。

1. ACME 在此处的工作方式#

PKI Trust Manager 提供 RFC 8555 ACME 服务器（CertAPI 的一部分）。客户端连接到 ACME directory URL，通过 External Account Binding (EAB) 注册账户，为域名创建订单，并接收由您的 CA 签发的证书。

ACME client ──https──▶ https://<acme-fqdn>/acme/directory (nginx → CertAPI)
 │ account (EAB) → order → finalize
 ▼
CAProxy(ca.ApiUrl) → caapi → ADCS → certificate
  • 必须使用 EAB。 directory 会公布 externalAccountRequired: true；服务器不接受未使用 EAB 的账户。
  • 域名验证可自动通过（在 ACME 应用中设置 RequireDomainValidation = 0），也可要求通过 http-01 / dns-01 验证。

2. 管理员设置 — 在 PKI Trust Manager 中启用 ACME#

每个 ACME 域名只需执行一次这些步骤（在 Web Admin UI 中或以管理员身份操作）。

  1. 创建 ACME 应用

    • Web Admin UI → Integrations → New
    • Type：ACME
    • Domain：ACME 主机名，例如 acme.secure.tron（必须与客户端发送的 Host 标头一致；不要包含端口）
    • Certificate template：选择关联到 CA 的模板（例如 Secure-WorkstationAuthentication → Secure-ISSUING-CA）
    • Require domain validation：设为 Off 以自动通过挑战，或设为 On 以使用 http-01/dns-01

  2. 创建 ACME (EAB) 用户/实体

    • Web Admin UI → Users → Create → 类型选择 ACME
    • 界面会生成并显示两个值，请保存：
    • Key ID (KID) — 例如 58913e5c-1690-455c-9a73-834586af9daf
    • HMAC key — 例如 OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk
    • 这些是客户端 EAB 凭据（--eab-kid / --eab-hmac-key）。

  3. DNS

    • 将 ACME FQDN 指向 PKI Trust Manager 服务器： acme.secure.tron → &lt;server IP&gt;

  4. 反向代理 (nginx) 路由

    • ACME FQDN 必须路由到 CertAPI。如果通过安装脚本部署，请将 FQDN 加入额外 ACME 域名（.env 中的 EXTRA_ACME_FQDNS，例如 acme,acme2,acme3,acme-eab.secure.tron），重新运行 nginx 更新（部署选项 2 — Add or Modify FQDNs）；或者将其加入 nginx.minimal.conf 中的 server_name，然后重新创建 nginx。
    • 验证：curl -k https://&lt;acme-fqdn&gt;/acme/directory 应返回 ACME directory。

  5. 客户设置（可选）

    • 为客户设置 Acme, Enabled = true（默认值）。
    • 自动签发时设置 CertificatePolicy, RequireApproval = false。

3. 客户端使用#

以下示例使用 acme-eab.secure.tron、KID 58913e5c-1690-455c-9a73-834586af9daf 和 HMAC OTiuWblfcWUzzxCkk4lPbrCrgWSB-h26UmakHGy04Lk。请替换为您自己的值。

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 / Windows WSL2)#

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

# 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. 验证#

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

在 Web Admin UI 中，注册项会显示在 Certificates 下，状态为 Issued。

5. 故障排查#

现象原因 / 解决办法
externalAccountRequired / EAB 错误使用 ACME 用户提供的有效 --eab-kid / --eab-hmac-key
创建账户时出现 serverInternal不支持非 EAB 方式 — 请始终使用 EAB
certbot: denied by the CAcertbot 默认选择 ECDSA 密钥 — 添加 --key-type rsa --rsa-key-size 2048
acme.sh: curl error 60TLS 证书为自签名 — 在实验环境使用 http:// directory URL，或信任该证书
certbot/win-acme: TLS 验证失败将自签名证书导入信任存储（仅限实验环境）
443 端口显示 Web UI 而不是 ACMEnginx server_name 缺少 ACME FQDN — 将其加入 EXTRA_ACME_FQDNS 并更新 nginx
new-order 出现 unauthorized客户的 Acme:Enabled 为 false
密钥长度被拒绝ADCS 模板设置了最小密钥长度 — 使用 RSA 2048
win-acme: "Run as administrator"SelfHosting 验证需要管理员权限 — 改用 --validation filesystem
win-acme: renewal-info 错误镜像中的服务端非阻塞问题；证书仍会签发

6. 参考 — ACME 端点#

端点端口
https://&lt;fqdn&gt;/acme/directory443
https://&lt;fqdn&gt;:8556/acme/directory8556 (ACME 专用本地端口)
http://&lt;fqdn&gt;/acme/directory80 (directory 会公布 http:// URL)