Модуль community.crypto.acme_certificate_order_validate — проверка авторизаций заказа 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_validate.

Добавлено в 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_finalize.

Требования

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

либо 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 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 целое число	Версия ACME конечной точки. Для стандартизированных конечных точек ACME v2 должно быть задано значение `2`. Значение `1` больше не поддерживается начиная с community.crypto 3.0.0. Варианты: `2` ← (по умолчанию)
challenge строка	Проверка, которую необходимо выполнить для каждой ожидающей авторизации. Необходимо задать, если есть хотя бы одна ожидающая авторизация. При повторном использовании авторизации или при работе с центрами сертификации, которые используют привязку внешней учетной записи и другие способы проверки соответствия сертификата требованиям, указывать этот параметр может быть не нужно. Поддержка `dns-account-01` и `dns-persist-01` добавлена в community.crypto 3.2.0. Варианты: `"http-01"` `"dns-01"` `"dns-account-01"` `"dns-persist-01"` `"tls-alpn-01"`
deactivate_authzs логическое значение	Деактивировать объекты аутентификации (authz) в случае ошибки. Объекты аутентификации привязаны к ключу учетной записи и остаются действительными в течение определенного времени. Их можно использовать для выпуска сертификатов без повторной аутентификации домена. Это может представлять угрозу безопасности. Варианты: `false` `true` ← (по умолчанию)
order_uri строка / обязательный	URI заказа, предоставленный модулем `order_uri`.
request_timeout целое число добавлено в community.crypto 2.3.0	Время ожидания ответа от API ACME для Ansible. Это значение тайм-аута применяется ко всем HTTP(S)-запросам (HEAD, GET, POST). По умолчанию: `10`
select_crypto_backend строка	Определяет, какую криптографическую серверную часть использовать. По умолчанию выбрано `auto`: сначала предпринимается попытка использовать `cryptography`, если она доступна, а в противном случае используется `openssl`. Если задано значение `openssl`, будет предпринята попытка использовать двоичный файл `openssl`. Если задано значение `cryptography`, будет предпринята попытка использовать библиотеку cryptography. Варианты: `"auto"` ← (по умолчанию) `"cryptography"` `"openssl"`
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	Поддержка: нет	В режиме различий будут возвращены сведения о том, что было изменено (или, возможно, нуждается в изменении в `check_mode`).
idempotent	Поддержка: полная	При повторном запуске с теми же аргументами вне режима проверки второй запуск не сообщает об изменениях. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.
safe_file_operations	Поддержка: полная	Использует строгие функции Ansible для работы с файлами, обеспечивая надлежащие разрешения и предотвращая повреждение данных.

Примечания

Примечание

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

См. также

community.crypto.acme_certificate_order_create: Создает заказ ACME.
community.crypto.acme_certificate_order_finalize: Завершает заказ ACME после выполнения проверок.
community.crypto.acme_certificate_order_info: Получает сведения о заказе ACME.
Документация Let’s Encrypt: Документация центра сертификации Let’s Encrypt. Содержит полезную информацию, например об ограничениях частоты запросов.
Среда автоматизированного управления сертификатами (ACME): Спецификация протокола ACME (RFC 8555).
Расширение ACME TLS ALPN Challenge: Спецификация проверки tls-alpn-01 (RFC 8737).
community.crypto.acme_challenge_cert_helper: Помогает подготовить проверки tls-alpn-01.
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 строка	URI учетной записи ACME. Возвращается: при успехе
validating_challenges список / элементы=словарь	Список проверок, для которых был запущен процесс валидации. Возвращается: при успехе
authz_url строка	URL объекта авторизации для этой проверки. Возвращается: всегда
challenge_type строка	Тип проверки. Возвращается: всегда Возможные возвращаемые значения: `"http-01"` `"dns-01"` `"tls-alpn-01"`
challenge_url строка	URL объекта проверки. Возвращается: всегда
identifier строка	Идентификатор, к которому относится проверка. Возвращается: всегда
identifier_type строка	Тип идентификатора для проверки. Возвращается: всегда Возможные возвращаемые значения: `"dns"` `"ip"`

Авторы

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