文档中心

Appearance

ACME 接入指南 ​

CertCloud 支持通过 ACME 协议自动签发和管理证书。整体对接分为四步：创建订单 → 获取 EAB 凭证 → ACME 客户端签发 → 接收回调通知。其中前两步调用 OpenAPI 完成，签发过程由 ACME 客户端按 ACME 协议（RFC 8555）与 ACME Server 交互完成，签发结果通过回调通知投递。

流程总览 ​

注意

¹ eab_mac_key 仅在创建成功时返回一次，服务端不保留明文，请妥善保存。丢失后只能通过轮换 EAB获取新凭证。

步骤 1：创建订单 ​

调用创建订单接口下单，记录返回的订单 ID。

  • 所选产品需支持 ACME，否则获取 EAB 时返回 33074（该产品目前不支持 ACME）。
  • 需要组织验证的产品，组织验证通过后才能获取 EAB，否则返回 order_org_validation_not_passed_for_acme_eab。

步骤 2：获取 EAB 凭证 ​

调用创建 ACME EAB接口，获取该订单的 ACME Directory URL 和 EAB 凭证：

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/orders/TIT6R0qv/acme-eab' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'
json
{
  "data": {
    "order_id": "TIT6R0qv",
    "directory": "https://acme.example.com/acme/v2/directory",
    "eab_kid": "eab-9f3k2d",
    "eab_mac_key": "c2VjcmV0LW1hYy1rZXk",
    "existing": false,
    "white_ips": []
  },
  "code": "success"
}
  • directory 与 eab_kid、eab_mac_key 用于下一步配置 ACME 客户端。
  • 本文示例中的 https://acme.example.com/acme/v2/directory 仅为示例地址，以接口实际返回的 directory 为准。
  • 重复调用返回现有凭证（existing=true），不再返回 eab_mac_key。
  • 可选：调用更新 EAB IP 白名单限制可使用该 EAB 的来源 IP。

步骤 3：ACME 客户端签发 ​

将 directory、eab_kid、eab_mac_key 配置到支持 EAB 的 ACME 客户端，由客户端完成账户注册、域名质询验证（http-01 / dns-01 等）和证书签发。以 acme.sh 为例：

bash
acme.sh --issue \
  --server https://acme.example.com/acme/v2/directory \
  --eab-kid eab-9f3k2d \
  --eab-hmac-key c2VjcmV0LW1hYy1rZXk \
  -d example.com --dns dns_dp

域名验证与 CSR 提交均由 ACME 客户端按 ACME 协议完成，无需再调用 OpenAPI 的 DCV 接口。

步骤 4：接收回调通知 ​

配置回调地址后（见账户回调配置），ACME 签发过程会产生以下事件（详见回调通知 · ACME 事件）：

action_id含义
acme:account_createdACME 账户注册（newAccount）完成
acme:certificate_issued证书已签发，携带 cert_id 与 acme_cert.full_chain_pem（完整证书链）
acme:cert_revoked证书已吊销
acme:account_deactivated客户端已通过 ACME 协议自行停用账户

acme:certificate_issued 事件的载荷中直接包含完整证书链 PEM，接收方无需再拉取即可入库；也可以凭 cert_id 调用获取证书详情获取证书。

运维操作 ​

  • 轮换 EAB：凭证泄露或 eab_mac_key 丢失时，调用轮换 EAB作废旧凭证并签发新凭证。轮换后旧 EAB 立即失效，ACME 客户端需用新凭证重新注册账户。
  • 续期：ACME 证书续期由 ACME 客户端发起新的签发请求完成。客户端可按 ARI（RFC 9773）通过 ACME Server 的 renewalInfo 端点查询建议续期窗口，并在该窗口内安排续期。

相关文档 ​