Модуль community.crypto.acme_certificate_order_finalize — завершение заказа ACME v2

Примечание

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

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

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

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

Добавлено в community.crypto 2.24.0

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

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

Завершает заказ ACME v2 и получает сертификат и цепочки сертификатов. Это последний шаг для получения нового сертификата с помощью протокола ACME от центра сертификации, например Let’s Encrypt. Этот модуль не поддерживает ACME v1 — исходную версию протокола ACME, существовавшую до его стандартизации.
Этот модуль необходимо использовать совместно с модулями community.crypto.acme_certificate_order_create и community.crypto.acme_certificate_order_validate.

Требования

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

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

Параметры

Параметр	Комментарии
account_key_content string	Содержимое ключа учетной записи ACME RSA или ключа на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Несовместим с `account_key_src`. Обязателен, если не используется `account_key_src`. Предупреждение: содержимое будет записано во временный файл, который Ansible удалит после завершения работы модуля. Поскольку это важный закрытый ключ — его можно использовать для смены ключа учетной записи или отзыва сертификатов, не зная их закрытых ключей, — такой способ может быть неприемлемым. Если используется `cryptography`, содержимое не записывается во временный файл. Однако Ansible все еще может записать его на диск в процессе передачи модуля с его аргументом на узел, где он выполняется.
account_key_passphrase string добавлено в community.crypto 1.6.0	Парольная фраза для расшифровки ключа учетной записи. Примечание: эта возможность не поддерживается бэкендом `openssl`, она поддерживается только бэкендом `cryptography`.
account_key_src псевдонимы: account_key path	Путь к файлу, содержащему ключ учетной записи 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 string	Если указано, модуль предполагает, что URI учетной записи соответствует заданному значению. Если ключ учетной записи не соответствует этой учетной записи или учетная запись с таким URI не существует, модуль завершится с ошибкой.
acme_directory string / обязательный	Используемый каталог ACME. Это URL-адрес точки входа для доступа к API сервера центра сертификации ACME. В целях безопасности по умолчанию используется тестовый сервер Let’s Encrypt (для протокола ACME v1). Он будет создавать технически корректные, но недоверенные сертификаты. Все тестовые конечные точки Let’s Encrypt перечислены здесь: https://letsencrypt.org/docs/staging-environment/. Для Let’s Encrypt URL-адрес рабочего каталога ACME v2: https://acme-v02.api.letsencrypt.org/directory. Для ZeroSSL URL-адрес рабочего каталога ACME v2: https://acme.zerossl.com/v2/DV90. Для Sectigo URL-адрес рабочего каталога ACME v2: https://acme-qa.secure.trust-provider.com/v2/DV. Для HARICA URL-адрес рабочего каталога ACME v2: https://acme.harica.gr/XXX/directory, где XXX — значение, уникальное для вашей учетной записи. В примечаниях к этому модулю приведен список служб ACME, с которыми модуль прошел тестирование.
acme_version integer	Версия ACME конечной точки. Для стандартизированных конечных точек ACME v2 должно быть указано `2`. Значение `1` больше не поддерживается начиная с community.crypto 3.0.0. Допустимые значения: `2` ← (по умолчанию)
cert_dest path	Файл назначения для сертификата.
chain_dest path	Если указано, промежуточный сертификат будет записан в этот файл.
csr path	Файл, содержащий CSR для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr. CSR может содержать несколько альтернативных имен субъекта, но для каждого из них будет создан отдельный запрос подтверждения, который необходимо выполнить, чтобы CSR был подписан. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учетной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать такой CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров `csr` или `csr_content`.
csr_content string	Содержимое CSR для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr_pipe. CSR может содержать несколько альтернативных имен субъекта, но для каждого из них будет создан отдельный запрос подтверждения, который необходимо выполнить, чтобы CSR был подписан. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учетной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать такой CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров `csr` или `csr_content`.
deactivate_authzs string	Деактивировать объекты аутентификации (authz) после выдачи сертификата или в случае неудачи при его выдаче. `never` никогда не деактивирует их. `always` всегда деактивирует их при возникновении ошибок или после выдачи сертификата. `on_error` деактивирует их только в случае ошибок. `on_success` деактивирует их только в случае успешной выдачи сертификата. Объекты аутентификации привязаны к ключу учетной записи и остаются действительными в течение определенного времени. Их можно использовать для выдачи сертификатов без повторной аутентификации домена. Это может представлять угрозу безопасности. Допустимые значения: `"never"` `"on_error"` `"on_success"` `"always"` ← (по умолчанию)
fullchain_dest path	Файл назначения для полной цепочки (то есть сертификата, за которым следует цепочка промежуточных сертификатов).
order_uri string / обязательный	URI заказа, предоставленный модулем `order_uri`.
request_timeout integer добавлено в community.crypto 2.3.0	Время, в течение которого Ansible ожидает ответа от API ACME. Это время ожидания применяется ко всем HTTP(S)-запросам (HEAD, GET, POST). По умолчанию: `10`
retrieve_all_alternates boolean	Если задано значение `true`, будут получены все альтернативные цепочки доверия, предлагаемые центром сертификации ACME. Они не будут записаны на диск, но будут возвращены вместе с основной цепочкой в виде `all_chains`. Подробности см. в документации к возвращаемому значению `all_chains`. Допустимые значения: `false` ← (по умолчанию) `true`
select_chain list / элементы=dictionary	Позволяет задать критерии выбора (альтернативной) цепочки доверия. Список критериев обрабатывается по порядку до тех пор, пока не будет найдена подходящая цепочка. Если такая цепочка найдена, модуль использует ее вместо цепочки по умолчанию. Если критерию соответствует несколько цепочек, будет возвращена первая подходящая. Порядок определяется расположением заголовков `Link`, возвращаемых сервером ACME, и может быть недетерминированным. Каждый критерий может состоять из нескольких разных условий, например `select_chain[].issuer` и `select_chain[].subject`. Чтобы цепочка соответствовала критерию, все условия должны выполняться для одного и того же сертификата в цепочке. Этот параметр можно использовать только с бэкендом `cryptography`.
authority_key_identifier string	Проверяет наличие расширения AuthorityKeyIdentifier. Это идентификатор, основанный на закрытом ключе издателя промежуточного сертификата. Идентификатор должен иметь формат `C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10`.
issuer dictionary	Позволяет указать части издателя сертификата в цепочке, которым он должен соответствовать для выбора. Если `select_chain[].issuer` пуст, подойдет любой сертификат. Примером значения может быть `{"commonName": "My Preferred CA Root"}`.
subject dictionary	Позволяет указать части субъекта сертификата в цепочке, которым он должен соответствовать для выбора. Если `select_chain[].subject` пуст, подойдет любой сертификат. Примером значения может быть `{"CN": "My Preferred CA Intermediate"}`
subject_key_identifier string	Проверяет наличие расширения SubjectKeyIdentifier. Это идентификатор, основанный на закрытом ключе промежуточного сертификата. Идентификатор должен иметь формат `A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1`.
test_certificates string	Определяет, какие сертификаты в цепочке будут проверяться. `all` проверяет все сертификаты в цепочке (кроме конечного, который одинаков во всех цепочках). `first` проверяет только первый сертификат в цепочке, то есть сертификат, подписавший конечный сертификат. `last` проверяет только последний сертификат в цепочке, то есть наиболее удаленный от конечного сертификата. Его издателем является корневой сертификат этой цепочки. Допустимые значения: `"first"` `"last"` `"all"` ← (по умолчанию)
select_crypto_backend string	Определяет, какой криптографический бэкенд использовать. По умолчанию выбирается `auto`: он пытается использовать `cryptography`, если тот доступен, и в противном случае переключается на `openssl`. Если задано значение `openssl`, модуль попытается использовать исполняемый файл `openssl`. Если задано значение `cryptography`, модуль попытается использовать библиотеку cryptography. Допустимые значения: `"auto"` ← (по умолчанию) `"cryptography"` `"openssl"`
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	Поддержка: none	Может выполняться в режиме `check_mode` и возвращать прогноз статуса изменений, не изменяя целевую систему.
diff_mode	Поддержка: none	В режиме diff будут возвращены сведения об изменениях (или возможных изменениях в `check_mode`).
idempotent	Поддержка: full	При последовательном запуске дважды вне режима проверки с одинаковыми аргументами второй запуск указывает на отсутствие изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась значимым образом.
safe_file_operations	Поддержка: full	Использует строгие функции Ansible для работы с файлами, чтобы обеспечить правильные разрешения и предотвратить повреждение данных.

Примечания

Примечание

Хотя значения по умолчанию выбраны так, чтобы модуль можно было использовать с центром сертификации Let’s Encrypt, в принципе модуль можно использовать с любым центром сертификации, предоставляющим конечную точку ACME.
На данный момент разработчики тестировали модули ACME только с Let’s Encrypt (тестовая и рабочая среды), ZeroSSL (рабочая среда) и тестовым сервером Pebble. Сообщество сообщало, что они также работают с Sectigo ACME Service для InCommon и HARICA. Если у вас возникнут проблемы с другим сервером ACME, пожалуйста, создайте задачу, чтобы помочь нам обеспечить его поддержку. Мы также будем благодарны за сообщения о том, что не упомянутый здесь сервер ACME работает.
Если доступна достаточно новая версия библиотеки cryptography (подробности см. в разделе «Требования»), она будет использоваться вместо исполняемого файла openssl. Ее можно явно отключить или включить с помощью параметра select_crypto_backend. Обратите внимание, что использование исполняемого файла openssl будет медленнее и менее безопасным, поскольку содержимое закрытого ключа всегда приходится хранить на диске (см. account_key_content).

См. также

community.crypto.acme_certificate_order_create: Создаёт заказ ACME.
community.crypto.acme_certificate_order_validate: Проверяет ожидающие авторизации заказа ACME.
community.crypto.acme_certificate_order_info: Получает информацию о заказе ACME.
Документация Let’s Encrypt: Документация центра сертификации Let’s Encrypt. Содержит полезную информацию, например о лимитах запросов.
Среда автоматического управления сертификатами (ACME): Спецификация протокола ACME (RFC 8555).
community.crypto.certificate_complete_chain: Позволяет найти корневой сертификат для возвращённой полной цепочки.
community.crypto.acme_certificate_revoke: Позволяет отзывать сертификаты.
community.crypto.acme_inspect: Позволяет отлаживать проблемы.
community.crypto.acme_certificate_deactivate_authz: Позволяет деактивировать (аннулировать) заказы ACME v2.

Примеры

---
### Example with HTTP-01 challenge ###

- name: Create a challenge for sample.com using a account key from a variable
  community.crypto.acme_certificate_order_create:
    account_key_content: "{{ account_private_key }}"
    csr: /etc/pki/cert/csr/sample.com.csr
  register: sample_com_challenge

# Alternative first step:
- name: Create a challenge for sample.com using a account key from Hashi Vault
  community.crypto.acme_certificate_order_create:
    account_key_content: >-
      {{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
    csr: /etc/pki/cert/csr/sample.com.csr
  register: sample_com_challenge

# Alternative first step:
- name: Create a challenge for sample.com using a account key file
  community.crypto.acme_certificate_order_create:
    account_key_src: /etc/pki/cert/private/account.key
    csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
  register: sample_com_challenge

# Perform the necessary steps to fulfill the challenge. For example:
#
# - name: Copy http-01 challenges
#   ansible.builtin.copy:
#     dest: /var/www/{{ item.identifier }}/{{ item.challenges['http-01'].resource }}
#     content: "{{ item.challenges['http-01'].resource_value }}"
#   loop: "{{ sample_com_challenge.challenge_data }}"
#   when: "'http-01' in item.challenges"

- name: Let the challenge be validated
  community.crypto.acme_certificate_order_validate:
    account_key_src: /etc/pki/cert/private/account.key
    order_uri: "{{ sample_com_challenge.order_uri }}"
    challenge: http-01

- name: Retrieve the cert and intermediate certificate
  community.crypto.acme_certificate_order_finalize:
    account_key_src: /etc/pki/cert/private/account.key
    csr: /etc/pki/cert/csr/sample.com.csr
    order_uri: "{{ sample_com_challenge.order_uri }}"
    cert_dest: /etc/httpd/ssl/sample.com.crt
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt

---
### Example with DNS challenge against production ACME server ###

- name: Create a challenge for sample.com using a account key file.
  community.crypto.acme_certificate_order_create:
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    csr: /etc/pki/cert/csr/sample.com.csr
  register: sample_com_challenge

# Perform the necessary steps to fulfill the challenge. For example:
#
# - name: Create DNS records for dns-01 challenges
#   community.aws.route53:
#     zone: sample.com
#     record: "{{ item.key }}"
#     type: TXT
#     ttl: 60
#     state: present
#     wait: true
#     # Note: item.value is a list of TXT entries, and route53
#     # requires every entry to be enclosed in quotes
#     value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
#   loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"

- name: Let the challenge be validated
  community.crypto.acme_certificate_order_validate:
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    order_uri: "{{ sample_com_challenge.order_uri }}"
    challenge: dns-01

- name: Retrieve the cert and intermediate certificate
  community.crypto.acme_certificate_order_finalize:
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    csr: /etc/pki/cert/csr/sample.com.csr
    order_uri: "{{ sample_com_challenge.order_uri }}"
    cert_dest: /etc/httpd/ssl/sample.com.crt
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt

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

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

Ключ	Описание
account_uri string	URI учётной записи ACME. Возвращается: при успехе
all_chains list / elements=dictionary	Если `retrieve_all_alternates=true`, модуль запросит у сервера ACME альтернативные цепочки. Это возвращаемое значение содержит список всех возвращённых цепочек; первая запись — основная цепочка, возвращённая сервером. Подробнее см. раздел 7.4.2 RFC 8555. Возвращается: при успехе и `retrieve_all_alternates=true`
cert string	Сам сертификат конечного узла в формате PEM. Возвращается: всегда
chain string	Цепочка сертификатов, не включающая корневой сертификат, представленная объединёнными сертификатами PEM. Возвращается: всегда
full_chain string	Цепочка сертификатов, не включающая корневой сертификат, но включающая сертификат конечного узла, представленная объединёнными сертификатами PEM. Возвращается: всегда
selected_chain dictionary	Выбранная цепочка сертификатов. Если `select_chain` не указано, это будет основная цепочка, возвращённая сервером ACME. Возвращается: при успехе
cert string	Сам сертификат конечного узла в формате PEM. Возвращается: всегда
chain string	Цепочка сертификатов, не включающая корневой сертификат, представленная объединёнными сертификатами PEM. Возвращается: всегда
full_chain string	Цепочка сертификатов, не включающая корневой сертификат, но включающая сертификат конечного узла, представленная объединёнными сертификатами PEM. Возвращается: всегда

Авторы

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_certificate_order_finalize_module.html