acme-companion EAB配置指南：ACME账户密钥外部绑定实现-优快云博客

acme-companion EAB配置指南：ACME账户密钥外部绑定实现

【免费下载链接】acme-companion Automated ACME SSL certificate generation for nginx-proxy 项目地址: https://gitcode.com/gh_mirrors/ac/acme-companion

在使用ACME（Automated Certificate Management Environment，自动化证书管理环境）协议申请SSL证书时，部分证书颁发机构（CA）要求使用EAB（External Account Binding，外部账户绑定）进行身份验证。EAB通过将ACME账户与CA提供的外部账户密钥绑定，增强了账户安全性。本文将详细介绍如何在acme-companion中配置EAB，实现ACME账户密钥的外部绑定。

EAB工作原理与配置准备

EAB要求ACME客户端在创建账户时提供由CA颁发的KID（Key Identifier，密钥标识符）和HMAC（Hash-based Message Authentication Code，基于哈希的消息认证码）密钥。这两个参数用于验证ACME账户与CA外部账户的关联性。

acme-companion通过环境变量ACME_EAB_KID和ACME_EAB_HMAC_KEY实现EAB配置。这两个变量可在acme-companion容器或被代理的应用容器中设置，应用容器的设置会覆盖acme-companion容器的全局设置。

EAB配置文件示例

测试环境中，Pebble（Let's Encrypt的测试CA）的EAB配置文件test/setup/pebble/pebble-config-eab.json定义了KID和HMAC密钥对：

{
  "pebble": {
    "externalAccountBindingRequired": true,
    "externalAccountMACKeys": {
      "kid-1": "zWNDZM6eQGHWpSRTPal5eIUYFTu7EajVIoguysqZ9wG44nMEtx3MUAsUDkMTQ12W",
      "kid-2": "b10lLJs8l1GPIzsLP0s6pMt8O0XVGnfTaCeROxQM0BIt2XrJMDHJZBM5NuQmQJQH"
    }
  }
}

全局EAB配置（acme-companion容器）

在启动acme-companion容器时，通过--env参数设置ACME_EAB_KID和ACME_EAB_HMAC_KEY，为所有未单独配置EAB的应用容器提供默认EAB参数。

Docker命令示例

docker run --detach \
    --name nginx-proxy-acme \
    --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
    --volume certs:/etc/nginx/certs:rw \
    --volume acme:/etc/acme.sh \
    --env "ACME_EAB_KID=kid-1" \
    --env "ACME_EAB_HMAC_KEY=zWNDZM6eQGHWpSRTPal5eIUYFTu7EajVIoguysqZ9wG44nMEtx3MUAsUDkMTQ12W" \
    nginxproxy/acme-companion

Docker Compose示例

services:
  acme:
    image: nginxproxy/acme-companion
    container_name: nginx-proxy-acme
    volumes:
      - certs:/etc/nginx/certs
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      ACME_EAB_KID: kid-1
      ACME_EAB_HMAC_KEY: zWNDZM6eQGHWpSRTPal5eIUYFTu7EajVIoguysqZ9wG44nMEtx3MUAsUDkMTQ12W

应用容器EAB配置（覆盖全局设置）

为特定应用容器配置EAB时，在应用容器中设置ACME_EAB_KID和ACME_EAB_HMAC_KEY环境变量，覆盖acme-companion的全局配置。

应用容器启动命令示例

docker run --detach \
    --name app-example \
    --env "VIRTUAL_HOST=example.com" \
    --env "LETSENCRYPT_HOST=example.com" \
    --env "ACME_EAB_KID=kid-2" \
    --env "ACME_EAB_HMAC_KEY=b10lLJs8l1GPIzsLP0s6pMt8O0XVGnfTaCeROxQM0BIt2XrJMDHJZBM5NuQmQJQH" \
    nginx

EAB配置验证与测试

acme-companion的测试用例test/tests/acme_eab/run.sh演示了EAB配置的验证过程。该脚本通过以下步骤验证EAB是否生效：

定义KID和HMAC密钥对：

declare -A eab=( \
  [kid-1]=zWNDZM6eQGHWpSRTPal5eIUYFTu7EajVIoguysqZ9wG44nMEtx3MUAsUDkMTQ12W \
  [kid-2]=b10lLJs8l1GPIzsLP0s6pMt8O0XVGnfTaCeROxQM0BIt2XrJMDHJZBM5NuQmQJQH \
)

启动acme-companion容器并设置EAB参数：

run_le_container "${1:?}" "$le_container_name" \
  --cli-args "--env ACME_EAB_KID=kid-1" \
  --cli-args "--env ACME_EAB_HMAC_KEY=${eab[kid-1]}"

验证EAB配置是否正确写入ACME账户配置文件：

config_path="/etc/acme.sh/default/ca/$ACME_CA/dir"
conf_file="${config_path}/ca.conf"
docker exec "$le_container_name" grep -q "${eab[kid-1]}" "$conf_file"

EAB配置常见问题解决

1. CA返回"invalid EAB credentials"错误

原因：KID或HMAC密钥不正确，或与CA提供的不匹配。
解决：检查ACME_EAB_KID和ACME_EAB_HMAC_KEY的值是否与CA提供的一致，注意密钥中是否包含多余的空格或特殊字符。

2. 部分应用容器EAB配置不生效

原因：应用容器未正确设置ACME_EAB_KID和ACME_EAB_HMAC_KEY，或acme-companion版本不支持应用容器级别的EAB配置。
解决：确保应用容器已设置EAB环境变量，且acme-companion版本不低于v2.2.0。

3. EAB配置后证书申请仍失败

原因：CA未启用EAB，或ACME_CA_URI指向的CA不支持EAB。
解决：确认CA是否要求EAB，如Pebble需设置externalAccountBindingRequired: true（见test/setup/pebble/pebble-config-eab.json）。

总结与最佳实践

EAB为ACME账户提供了额外的安全保障，特别适用于需要严格身份验证的企业环境。在使用acme-companion配置EAB时，建议：

全局配置与应用配置分离：为大多数应用使用acme-companion容器的全局EAB配置，为特殊应用在其容器中单独设置EAB参数。
使用测试CA验证配置：在生产环境中应用EAB前，使用Pebble等测试CA验证配置的正确性，避免触发生产CA的速率限制。
定期轮换EAB密钥：按照CA的建议定期轮换KID和HMAC密钥，并通过acme-companion的ACME_POST_HOOK实现密钥轮换后的自动部署。

通过本文的指南，您可以在acme-companion中轻松实现EAB配置，增强ACME账户的安全性与合规性。更多高级配置选项可参考官方文档docs/Container-configuration.md。

【免费下载链接】acme-companion Automated ACME SSL certificate generation for nginx-proxy 项目地址: https://gitcode.com/gh_mirrors/ac/acme-companion

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考