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

Примечание

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

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

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

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

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

Обзор

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

Требования

Ниже перечислены требования к хосту, на котором выполняется этот модуль.

либо openssl, либо cryptography >= 1.5
ipaddress

END_OF_DOCUMENT_MARKER

Параметры

Параметр	Комментарии
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`: ключи RSA можно создать с помощью `openssl genrsa ...`, а ключи эллиптической кривой — с помощью `openssl ecparam -genkey ...`. Также можно использовать любой другой инструмент, создающий закрытые ключи в формате PEM. Взаимоисключающее с `account_key_content`. Требуется, если `account_key_content` не используется.
account_uri строка	Если указано, предполагается, что URI учетной записи задан так, как указано. Если ключ учетной записи не соответствует этой учетной записи или учетная запись с этим URI не существует, модуль завершается с ошибкой.
acme_directory строка / обязательно	Используемый каталог ACME. Это URL-адрес точки входа для доступа к API сервера CA ACME. Для безопасности по умолчанию используется эталонный сервер Let’s Encrypt (для протокола ACME v1). Это создаст технически корректные, но недоверенные сертификаты. Все эталонные конечные точки Let’s Encrypt можно найти здесь: https://letsencrypt.org/docs/staging-environment/. Для Buypass все конечные точки можно найти здесь: https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints Для Let’s Encrypt, URL каталога для ACME v2 — https://acme-v02.api.letsencrypt.org/directory. Для Buypass, URL каталога для ACME v2 и v1 — https://api.buypass.com/acme/directory. Для ZeroSSL, URL каталога для ACME v2 — https://acme.zerossl.com/v2/DV90. Для Sectigo, URL каталога для ACME v2 — https://acme-qa.secure.trust-provider.com/v2/DV. Примечания к этому модулю содержат список сервисов ACME, с которыми был протестирован этот модуль.
acme_version целое число / обязательно	Версия ACME конечной точки. Должно быть `1`, для классических конечных точек ACME Let’s Encrypt и Buypass, или `2` для стандартизированных конечных точек ACME v2. Значение `1` устарело с community.crypto 2.0.0 и будет удалено из 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	Позволяет предоставить данные внешней привязки учетной записи во время создания учетной записи. Это используется CA, такими как Sectigo, для привязки новой учетной записи ACME к существующей учетной записи CA, чтобы правильно идентифицировать клиента. Используется только при создании новой учетной записи. Не может быть указан для ACME v1.
alg строка / обязательно	Алгоритм MAC, предоставленный CA. Если не указан CA, это, вероятно, `HS256`. Варианты: `"HS256"` `"HS384"` `"HS512"`
key строка / обязательно	Значение ключа MAC, закодированное в Base64 URL, предоставленное CA. Заполнение (`=` символы в конце) может быть опущено.
kid строка / обязательно	Идентификатор ключа, предоставленный CA.

END_OF_DOCUMENT_MARKER

new_account_key_content string	Содержимое ключа учетной записи ACME RSA или эллиптической кривой, на который нужно заменить. Применяются те же ограничения, что и к `account_key_content`. Взаимоисключающие с `new_account_key_src`. Требуется, если `new_account_key_src` не используется и `state` равно `changed_key`.
new_account_key_passphrase string добавлено в community.crypto 1.6.0	Фраза-пароль для декодирования нового ключа учетной записи. Примечание: это не поддерживается бэкендом `openssl`, только бэкендом `cryptography`.
new_account_key_src path	Путь к файлу, содержащему ключ учетной записи ACME RSA или эллиптической кривой, на который нужно заменить. Применяются те же ограничения, что и к `account_key_src`. Взаимоисключающие с `new_account_key_content`. Требуется, если `new_account_key_content` не используется и `state` равно `changed_key`.
request_timeout integer добавлено в community.crypto 2.3.0	Время, которое Ansible должно ждать ответа от API ACME. Этот таймаут применяется ко всем запросам HTTP(S) (HEAD, GET, POST). По умолчанию: `10`
select_crypto_backend string	Определяет, какой криптографический бэкенд использовать. По умолчанию выбирается `auto`, который пытается использовать `cryptography`, если он доступен, и переходит к `openssl`. Если установлено `openssl`, будет попытка использовать двоичный файл `openssl`. Если установлено `cryptography`, будет попытка использовать библиотеку cryptography. Варианты: `"auto"` ← (по умолчанию) `"cryptography"` `"openssl"`
state string / обязательно	Состояние учетной записи, определяемое по ключу учетной записи. Если состояние `absent`, учетная запись либо не существует, либо деактивирована. Если состояние `changed_key`, учетная запись должна существовать. Ключ учетной записи будет изменен; никакая другая информация не будет затронута. Варианты: `"present"` `"absent"` `"changed_key"`
terms_agreed boolean	Булево значение, указывающее, согласны ли вы с документом соглашения об использовании. Серверы ACME могут потребовать, чтобы это было `true`. Варианты: `false` ← (по умолчанию) `true`
validate_certs boolean	Подтверждать ли сертификаты 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	Поддержка: полная	Возвращает подробную информацию о том, что изменилось (или, возможно, требует изменения в `check_mode`), при работе в режиме сравнения.

Примечания

Примечание

Модуль community.crypto.acme_certificate также позволяет выполнять основные операции по управлению учетными записями. При использовании обоих модулей рекомендуется отключить управление учетными записями для community.crypto.acme_certificate. Для этого используйте параметр modify_account модуля community.crypto.acme_certificate.
Хотя значения по умолчанию выбраны таким образом, чтобы модуль можно было использовать с центром сертификации Let’s Encrypt, модуль в принципе может использоваться с любым центром сертификации, предоставляющим конечную точку ACME, например, Buypass Go SSL.
До сих пор модули ACME тестировались разработчиками только с Let’s Encrypt (этап и производство), Buypass (этап и производство), ZeroSSL (производство) и Pebble test server. Мы получили обратную связь от сообщества, что они также работают с 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: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–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/crypto/acme_account_module.html