Модуль community.crypto.acme_account — создание, изменение или удаление учетных записей ACME

Примечание

Этот модуль входит в коллекцию community.crypto (версия 3.2.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.crypto. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.crypto.acme_account.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Позволяет создавать, изменять или удалять учетные записи в центре сертификации, поддерживающем протокол ACME, например в Let’s Encrypt.
Этот модуль работает только с протоколом ACME версии 2.

Требования

На узле, выполняющем этот модуль, должны быть установлены следующие компоненты.

либо openssl
либо cryptography >= 3.3

Параметры

Параметр	Комментарии
account_key_content строка	Содержимое ключа учетной записи ACME RSA или ключа на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Взаимоисключающий параметр с `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 или ключ на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Закрытые ключи можно создать с помощью модулей community.crypto.openssl_privatekey или community.crypto.openssl_privatekey_pipe. Если необходимая библиотека (cryptography) недоступна, ключи также можно создать непосредственно с помощью инструмента командной строки `openssl`: ключи RSA можно создать с помощью `openssl genrsa ...`. Ключи на эллиптических кривых можно создать с помощью `openssl ecparam -genkey ...`. Также можно использовать любой другой инструмент для создания закрытых ключей в формате PEM. Взаимоисключающий параметр с `account_key_content`. Обязателен, если не используется `account_key_content`.
account_uri строка	Если указано, предполагается, что URI учетной записи соответствует заданному значению. Если ключ учетной записи не соответствует этой учетной записи или учетная запись с таким URI не существует, модуль завершится с ошибкой.
acme_directory строка / обязательный	Каталог ACME, который необходимо использовать. Это URL-адрес точки входа для доступа к API сервера центра сертификации ACME. Из соображений безопасности по умолчанию используется тестовый сервер Let’s Encrypt (для протокола ACME версии 1). Он будет создавать технически корректные, но недоверенные сертификаты. Все тестовые конечные точки Let’s Encrypt перечислены здесь: https://letsencrypt.org/docs/staging-environment/. Для Let’s Encrypt URL-адрес рабочего каталога ACME версии 2: https://acme-v02.api.letsencrypt.org/directory. Для ZeroSSL URL-адрес рабочего каталога ACME версии 2: https://acme.zerossl.com/v2/DV90. Для Sectigo URL-адрес рабочего каталога ACME версии 2: https://acme-qa.secure.trust-provider.com/v2/DV. Для HARICA URL-адрес рабочего каталога ACME версии 2: https://acme.harica.gr/XXX/directory, где XXX — значение, уникальное для вашей учетной записи. В примечаниях к этому модулю приведен список служб ACME, с которыми он был протестирован.
acme_version целое число	Версия ACME конечной точки. Для стандартизированных конечных точек ACME версии 2 должно быть задано значение `2`. Значение `1` больше не поддерживается начиная с community.crypto 3.0.0. Варианты: `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, HARICA или ZeroSSL, чтобы связать новую учетную запись ACME с существующей учетной записью центра сертификации и обеспечить корректную идентификацию клиента. Используется только при создании новой учетной записи. Для ACME версии 1 указать нельзя.
alg строка / обязательный	Алгоритм MAC, предоставленный центром сертификации. Если центр сертификации не указал алгоритм, вероятно, это `HS256`. Варианты: `"HS256"` `"HS384"` `"HS512"`
key строка / обязательный	Значение ключа MAC, предоставленного центром сертификации, в кодировке Base64 URL. Допускается не указывать заполнение (символы `=` в конце).
kid строка / обязательный	Идентификатор ключа, предоставленный центром сертификации.
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 ожидает ответа от API ACME. Это значение времени ожидания применяется ко всем 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 логическое значение	Проверять ли TLS-сертификаты при обращении к каталогу ACME. Предупреждение: устанавливайте значение `false` только для тестирования, например при проверке с локальным сервером Pebble. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группы действий: community.crypto.acme, acme	Используйте `group/acme` или `group/community.crypto.acme` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: полная	Может выполняться в режиме `check_mode` и возвращать прогноз изменения состояния, не изменяя целевой узел.
diff_mode	Поддержка: полная	В режиме diff будут возвращены сведения о внесенных изменениях (или о тех, которые, возможно, необходимо внести в `check_mode`).
idempotent	Поддержка: частичная При использовании `state=changed_key` модуль не является идемпотентным.	При повторном запуске с теми же аргументами вне режима проверки модуль сообщает об отсутствии изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.

Примечания

Примечание

Модуль community.crypto.acme_certificate также поддерживает базовое управление учетными записями. При использовании обоих модулей рекомендуется отключить управление учетными записями для community.crypto.acme_certificate. Для этого используйте параметр modify_account модуля community.crypto.acme_certificate.
Хотя значения по умолчанию выбраны таким образом, чтобы модуль можно было использовать с центром сертификации Let’s Encrypt, в принципе он совместим с любым центром сертификации, предоставляющим конечную точку ACME.
На данный момент разработчики тестировали модули ACME только с Let’s Encrypt (тестовая и рабочая среды), ZeroSSL (рабочая среда) и тестовым сервером Pebble. Сообщество сообщило, что они также работают с Sectigo ACME Service for InCommon и HARICA. Если у вас возникли проблемы с другим сервером 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

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже приведены поля, уникальные для этого модуля:

Ключ	Описание
account_uri строка	URI учетной записи ACME или None, если учетная запись не существует. Возвращается: всегда

Авторы

Felix Fontein (@felixfontein)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/crypto/acme_account_module.html