community.crypto.acme_account 模块 – 创建、修改或删除 ACME 帐户

注意

此模块是 community.crypto 集合（版本 2.22.3）的一部分。

如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.crypto。您需要其他要求才能使用此模块，请参阅要求了解详细信息。

要在 playbook 中使用它，请指定：community.crypto.acme_account。

概要 

允许使用支持 ACME 协议的 CA 创建、修改或删除帐户，例如 Let’s Encrypt。
此模块仅适用于 ACME v2 协议。

要求 

执行此模块的主机需要满足以下要求。

openssl 或 cryptography >= 1.5
ipaddress

参数 

参数	注释
account_key_content 字符串	ACME 帐户 RSA 或椭圆曲线密钥的内容。与 `account_key_src` 互斥。如果未使用 `account_key_src`，则为必填项。警告：该内容将被写入临时文件，该文件将在模块完成时被 Ansible 删除。由于这是一个重要的私钥 — 它可用于更改帐户密钥，或在不知道其私钥的情况下撤销您的证书 — 这可能是不可接受的。如果使用 `cryptography`，则内容不会写入临时文件。仍然有可能在 Ansible 将带有参数的模块移动到执行它的节点的过程中将其写入磁盘。
account_key_passphrase 字符串在 community.crypto 1.6.0 中添加	用于解码帐户密钥的密码。注意： `openssl` 后端不支持此功能，只有 `cryptography` 后端支持此功能。
account_key_src 别名：account_key 路径	包含 ACME 帐户 RSA 或椭圆曲线密钥的文件路径。可以使用 community.crypto.openssl_privatekey 或 community.crypto.openssl_privatekey_pipe 模块创建私钥。如果所需的（加密）不可用，也可以直接使用 `openssl` 命令行工具创建密钥：可以使用 `openssl genrsa ...` 创建 RSA 密钥。可以使用 `openssl ecparam -genkey ...` 创建椭圆曲线密钥。也可以使用任何其他以 PEM 格式创建私钥的工具。与 `account_key_content` 互斥。如果未使用 `account_key_content`，则为必填项。
account_uri 字符串	如果指定，则假定帐户 URI 与给定 URI 相同。如果帐户密钥与此帐户不匹配，或者不存在具有此 URI 的帐户，则模块将失败。
acme_directory 字符串 / 必需	要使用的 ACME 目录。这是访问 ACME CA 服务器 API 的入口点 URL。出于安全原因，默认设置为 Let's Encrypt 暂存服务器（用于 ACME v1 协议）。这将创建技术上正确但不受信任的证书。对于 Let's Encrypt，所有暂存端点都可以在这里找到：https://letsencrypt.openssl.ac.cn/docs/staging-environment/。对于 Buypass，所有端点都可以在这里找到：https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints 对于 Let's Encrypt，ACME v2 的生产目录 URL 为 https://acme-v02.api.letsencrypt.org/directory。对于 Buypass，ACME v2 和 v1 的生产目录 URL 为 https://api.buypass.com/acme/directory。对于 ZeroSSL，ACME v2 的生产目录 URL 为 https://acme.zerossl.com/v2/DV90。对于 Sectigo，ACME v2 的生产目录 URL 为 https://acme-qa.secure.trust-provider.com/v2/DV。此模块的说明包含此模块已测试的 ACME 服务列表。
acme_version 整数 / 必需	端点的 ACME 版本。对于经典的 Let's Encrypt 和 Buypass ACME 端点，必须为 `1`，对于标准化的 ACME v2 端点，必须为 `2`。从 community.crypto 2.0.0 开始，值 `1` 已被弃用，并将从 community.crypto 3.0.0 中删除。选项 `1` `2`
allow_creation 布尔值	是否允许创建帐户（当状态为 `present` 时）。选项 `false` `true` ← (默认)
联系方式列表 / 元素=字符串	联系 URL 的列表。电子邮件地址必须以 `mailto:` 为前缀。有关允许的内容，请参阅 https://tools.ietf.org/html/rfc8555#section-7.3。当 state 为 `present` 时，必须指定。如果 state 为 `absent` 或 `changed_key`，则会被忽略。默认值: `[]`
external_account_binding 字典在 community.crypto 1.1.0 中添加	允许在创建帐户期间提供外部帐户绑定数据。这被诸如 Sectigo 之类的 CA 用来将新的 ACME 帐户绑定到现有的 CA 特定帐户，以便能够正确识别客户。仅在创建新帐户时使用。不能为 ACME v1 指定。
alg 字符串 / 必需	CA 提供的 MAC 算法。如果 CA 未指定，则可能为 `HS256`。选项 `"HS256"` `"HS384"` `"HS512"`
key 字符串 / 必需	CA 提供的 MAC 密钥的 Base64 URL 编码值。可以省略填充（末尾的 `=` 符号）。
kid 字符串 / 必需	CA 提供的密钥标识符。
new_account_key_content 字符串	要更改的 ACME 帐户 RSA 或椭圆曲线密钥的内容。与 `account_key_content` 适用相同的限制。与 `new_account_key_src` 互斥。如果未使用 `new_account_key_src` 且 `state` 为 `changed_key`，则为必填项。
new_account_key_passphrase 字符串在 community.crypto 1.6.0 中添加	用于解码新帐户密钥的密码。注意： `openssl` 后端不支持此功能，只有 `cryptography` 后端支持此功能。
new_account_key_src 路径	包含要更改的 ACME 帐户 RSA 或椭圆曲线密钥的文件路径。与 `account_key_src` 适用相同的限制。与 `new_account_key_content` 互斥。如果未使用 `new_account_key_content` 且 `state` 为 `changed_key`，则为必填项。
request_timeout 整数在 community.crypto 2.3.0 中添加	Ansible 应等待 ACME API 响应的时间。此超时适用于所有 HTTP(S) 请求（HEAD、GET、POST）。默认值: `10`
select_crypto_backend 字符串	确定要使用的加密后端。默认选择是 `auto`，它会尝试使用 `cryptography` （如果可用），并回退到 `openssl`。如果设置为 `openssl`，将尝试使用 `openssl` 二进制文件。如果设置为 `cryptography`，将尝试使用 cryptography 库。选项 `"auto"` ← (默认) `"cryptography"` `"openssl"`
state 字符串 / 必需	帐户的状态，由其帐户密钥标识。如果状态为 `absent`，则帐户将不存在或被禁用。如果状态为 `changed_key`，则帐户必须存在。将更改帐户密钥；不会触及其他信息。选项 `"present"` `"absent"` `"changed_key"`
terms_agreed 布尔值	布尔值，指示您是否同意服务条款文档。 ACME 服务器可能要求此值为 `true`。选项 `false` ← (默认) `true`
validate_certs 布尔值	对 ACME 目录的调用是否验证 TLS 证书。警告: 仅应出于测试目的将其设置为 `false`，例如在针对本地 Pebble 服务器进行测试时。选项 `false` `true` ← (默认)

属性 

属性	支持	描述
action_group	操作组: community.crypto.acme, acme	在 `module_defaults` 中使用 `group/acme` 或 `group/community.crypto.acme` 来为此模块设置默认值。
check_mode	支持: 完全	可以在 `check_mode` 中运行，并返回更改状态预测，而无需修改目标。
diff_mode	支持: 完全	当处于差异模式时，将返回有关已更改的内容（或可能需要在 `check_mode` 中更改的内容）的详细信息。

注意 

注意

community.crypto.acme_certificate 模块还允许进行基本的帐户管理。当同时使用这两个模块时，建议禁用 community.crypto.acme_certificate 的帐户管理。为此，请使用 community.crypto.acme_certificate 的 modify_account 选项。
虽然默认值经过选择，以便该模块可以与 Let’s Encrypt CA 一起使用，但原则上该模块可以与任何提供 ACME 端点的 CA 一起使用，例如 Buypass Go SSL。
到目前为止，ACME 模块仅由开发人员针对 Let’s Encrypt（暂存和生产）、Buypass（暂存和生产）、ZeroSSL（生产）和 Pebble 测试服务器进行了测试。我们收到了社区反馈，它们也适用于 Sectigo 为 InCommon 提供的 ACME 服务。如果您在使用其他 ACME 服务器时遇到问题，请创建一个问题，以帮助我们支持它。我们也感谢关于未提及的 ACME 服务器可以正常工作的反馈。
如果可用足够新版本的 cryptography 库（有关详细信息，请参阅要求），它将代替 openssl 二进制文件使用。可以使用 select_crypto_backend 选项显式禁用或启用此功能。请注意，使用 openssl 二进制文件会更慢且安全性更低，因为私钥内容始终必须存储在磁盘上（请参阅 account_key_content）。

另请参阅 

另请参阅

自动证书管理环境 (ACME): ACME 协议的规范（RFC 8555）。
community.crypto.acme_account_info: 检索有关 ACME 帐户的事实。
community.crypto.openssl_privatekey: 可用于创建私有帐户密钥。
community.crypto.openssl_privatekey_pipe: 可用于创建私有帐户密钥，而无需将其写入磁盘。
community.crypto.acme_inspect: 允许调试问题。

示例 

- name: Make sure account exists and has given contacts. We agree to TOS.
  community.crypto.acme_account:
    account_key_src: /etc/pki/cert/private/account.key
    state: present
    terms_agreed: true
    contact:
    - mailto:me@example.com
    - mailto:myself@example.org

- name: Make sure account has given email address. Do not create account if it does not exist
  community.crypto.acme_account:
    account_key_src: /etc/pki/cert/private/account.key
    state: present
    allow_creation: false
    contact:
    - mailto:me@example.com

- name: Change account's key to the one stored in the variable new_account_key
  community.crypto.acme_account:
    account_key_src: /etc/pki/cert/private/account.key
    new_account_key_content: '{{ new_account_key }}'
    state: changed_key

- name: Delete account (we have to use the new key)
  community.crypto.acme_account:
    account_key_content: '{{ new_account_key }}'
    state: absent

返回值 

常见的返回值记录在这里，以下是此模块特有的字段

Key	描述
account_uri 字符串	ACME 账户 URI，如果账户不存在则为 None。返回值: 总是

作者

Felix Fontein (@felixfontein)

community.crypto.acme_account 模块 – 创建、修改或删除 ACME 帐户

作者

集合链接