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 协议。

要求

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

参数

参数

注释

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 模块创建私钥。如果必备条件（cryptography）不可用，也可以直接使用 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 ← (默认)

contact

列表 / 元素=字符串

联系人 URL 列表。

电子邮件地址必须以 mailto: 为前缀。

有关允许的内容，请参阅 https://tools.ietf.org/html/rfc8555#section-7.3。

当状态为 present 时，必须指定此项。 如果状态为 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 ACME Service for InCommon 配合使用。 如果您在使用其他 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:[email protected]
    - mailto:[email protected]

- 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:[email protected]

- 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

返回值

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

键

描述

account_uri

字符串

ACME 账户 URI，如果账户不存在则为 None。

返回： 总是

作者

  • Felix Fontein (@felixfontein)