felixfontein.acme.acme_certificate role – Issue TLS/SSL certificates from an ACME CA

Note

This role is part of the felixfontein.acme collection (version 0.8.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install felixfontein.acme.

To use it in a playbook, specify: felixfontein.acme.acme_certificate.

Entry point main – Issue TLS/SSL certificates from an ACME CA

New in felixfontein.acme 0.1.0

Synopsis

  • This is a role which can use any CA supporting the ACME protocol, such as Let’s Encrypt, Buypass or ZeroSSL, to issue TLS/SSL certificates for your server.

  • The main advantage of this approach over others is that almost no code is executed on your webserver: only when you use HTTP challenges, files need to be copied onto your webserver, and afterwards deleted from it. Everything else is executed on your local machine! In particular, the account key is never sent to another machine.

  • This role does not cover installing the certificates, you have to do that yourself in another role.

Parameters

Parameter

Comments

acme_certificate_acme_account

string

Path to the private ACME account key. Either this or acme_certificate_acme_account_content must always be specified.

acme_certificate_acme_account_content

string

Content of the private ACME account key. Either this or acme_certificate_acme_account must always be specified.

acme_certificate_acme_account_uri

string

Instead of determining the account URI from the account key, assumes the given account URI.

acme_certificate_acme_directory

string

The ACME directory to use.

Default is https://acme-v02.api.letsencrypt.org/directory, which is the current production ACME v2 endpoint of Let’s Encrypt.

Default: "https://acme-v02.api.letsencrypt.org/directory"

acme_certificate_acme_email

string

Your email address which shall be associated to the ACME account.

acme_certificate_acme_version

integer

The ACME directory’s version.

Default: 2

acme_certificate_algorithm

string

The algorithm used for creating private keys.

The default is rsa for RSA keys.

Other choices are p-256, p-384 or p-521 for the NIST elliptic curves prime256v1, secp384r1 and secp521r1, respectively.

Choices:

  • "rsa" ← (default)

  • "p-256"

  • "p-384"

  • "p-521"

acme_certificate_aws_access_key

string

When using acme_certificate_dns_provider=route53, the AWS access key for Route53 must be passed in this option.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=route53 and can be provided in other ways, for example with module defaults.

acme_certificate_aws_secret_key

string

When using acme_certificate_dns_provider=route53, the AWS secret key for Route53 must be passed in this option.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=route53 and can be provided in other ways, for example with module defaults.

acme_certificate_challenge

string

The challenge type to use.

Should be http-01 for HTTP challenges (needs access to web server) or dns-01 for DNS challenges (needs access to DNS provider).

Choices:

  • "http-01"

  • "dns-01"

acme_certificate_cloudflare_token

string

added in felixfontein.acme 0.7.0

When using acme_certificate_dns_provider=cloudflare, a valid Cloudflare API token must be passed via this option.

acme_certificate_deactivate_authzs

boolean

Whether authz objects (authorizations) should be deactivated afterwards.

Set to false to be able to re-use authz objects. This should mostly be used when issuing multiple certificates for the same domain names.

Choices:

  • false

  • true ← (default)

acme_certificate_dns_propagation_timeout

integer

added in felixfontein.acme 0.9.0

Default timeout when waiting for DNS entries to propagate for dns-01 challenges.

This is passed to the timeout option of community.dns.wait_for_txt.

The default depends on acme_certificate_dns_provider.

acme_certificate_dns_provider

string

Determines which DNS provider is used for DNS challenges.

Every DNS provider requires further configuration.

The value ansibletest must not be used outside of integration tests. It will not work.

Choices:

  • "route53"

  • "hosttech"

  • "ns1"

  • "inwx"

  • "cloudflare"

  • "ansibletest"

acme_certificate_dns_servers

list / elements=string

added in felixfontein.acme 0.9.0

DNS servers to use to lookup the name servers of the domains. These are queried to ensure that the dns-01 challenges propagated before the ACME CA is asked to validate the challenges.

If not provided, the system’s standard resolver is used.

This is passed to the server option of community.dns.wait_for_txt.

acme_certificate_dns_substitution

dictionary

added in felixfontein.acme 0.6.0

Allows to substitute parts of the DNS entry domain names. This can be very useful if certificates are obtained for domain names that are CNAMEs, and the DNS provider for where the CNAME points need to be modified.

The entries in this dictionary should be the names that are to be replaced, and the values the replacements. A single leading wildcard can be used to replace suffixes instead of the complete string, assuming the prefix has no further period (.).

For example, if the key is *.example.com and the value *.foo.example.org, the name _acme-challenge.example.com will be replaced by *.foo.example.org. If the key is *.example.com and the value foo.example.org, the name _acme-challenge.example.com will be replaced by foo.example.org. And if the key is example.com and the value foo.example.org, _acme-challenge.example.com will not be changed at all, only example.com will be changed to foo.example.org.

Note that if you want to obtain certificates with ACME with acme_certificate_challenge=dns-01 for example.com whose CNAME is foo.example.org, you should create (and provide in this variable) another CNAME record *.example.com, or _acme-challenge.example.com if it should be more specialized.

Default: {}

acme_certificate_domains

string

The domain names you want to get a certificate for.

Wildcards are only allowed as the first component, i.e. *.example.com is ok, while *.*.example.com and www.*.example.com are not ok.

Also, when wildcards are used, not every challenge type is allowed. Let’s Encrypt only allows wildcard domains with the dns-01 challenge. At least one of acme_certificate_domains and acme_certificate_ips must be specified.

acme_certificate_hosttech_password

string

When using acme_certificate_dns_provider=hosttech with the old HostTech WSDL API, the API password must be passed in this option.

We recommend to use acme_certificate_hosttech_token instead of acme_certificate_hosttech_username and acme_certificate_hosttech_password.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=hosttech and can be provided in other ways, for example with module defaults.

acme_certificate_hosttech_token

string

When using acme_certificate_dns_provider=hosttech with the new HostTech JSON REST API, the API token must be passed in this option.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=hosttech and can be provided in other ways, for example with module defaults.

acme_certificate_hosttech_username

string

When using acme_certificate_dns_provider=hosttech with the old HostTech WSDL API, the API username must be passed in this option.

We recommend to use acme_certificate_hosttech_token instead of acme_certificate_hosttech_username and acme_certificate_hosttech_password.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=hosttech and can be provided in other ways, for example with module defaults.

acme_certificate_http_become

boolean

Argument for become: for the ansible.builtin.file and ansible.builtin.copy tasks.

Choices:

  • false ← (default)

  • true

acme_certificate_http_challenge_file_mode

string

The mode to use for the challenge files.

Default: "0640"

acme_certificate_http_challenge_folder_mode

string

The mode to use for the challenge folder.

Default: "0750"

acme_certificate_http_challenge_group

string

The group the challenge files are owned by.

Default: "http"

acme_certificate_http_challenge_user

string

The user the challenge files are owned by.

Default: "root"

acme_certificate_inwx_password

string

When using acme_certificate_dns_provider=inwx, the INWX account password must be passed in this option.

Please note that INWX support depends on the collection inwx.collection. Please check out the documentation on how to install it.

Please note that the collection inwx.collection does currently not support 2FA (two factor authentication). In order to use this module you need to disable it.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=inwx and can be provided in other ways, for example with module defaults.

acme_certificate_inwx_username

string

When using acme_certificate_dns_provider=inwx, the INWX account username must be passed in this option.

Please note that INWX support depends on the collection inwx.collection. Please check out the documentation on how to install it.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=inwx and can be provided in other ways, for example with module defaults.

acme_certificate_ips

string

The IP addresses you want to get a certificate for.

Note that this is not supported by every CA!

At least one of acme_certificate_domains and acme_certificate_ips must be specified.

acme_certificate_key_length

integer

The bit-size to use for RSA private keys.

Should not be less than 2048. Also values above 4096 might not be supported by all TLS/SSL clients.

Default: 4096

acme_certificate_key_name

string

The basename for storing the keys and certificates.

The default is the first domain specified, with * replaced by _.

acme_certificate_keys_old_path

string

Where old keys and certificates should be copied to.

Used in case acme_certificate_keys_old_store=true.

Default: "keys/old/"

acme_certificate_keys_old_prepend_timestamp

boolean

Whether copies of old keys and certificates should be prepended by the current date and time.

Choices:

  • false ← (default)

  • true

acme_certificate_keys_old_store

boolean

If set to true, will make copies of old keys and certificates.

The copies will be stored in the directory specified by acme_certificate_keys_old_path.

Choices:

  • false ← (default)

  • true

acme_certificate_keys_path

string

Where the keys and certificates are stored.

Default: "keys/"

acme_certificate_modify_account

boolean

Whether the ACME account should be created (if it doesn’t exist) and the contact data (email address) should be updated.

Set to false if you want to use the community.crypto.acme_account module to manage your ACME account (not done by this role).

Choices:

  • false

  • true ← (default)

acme_certificate_ns1_secret_key

string

When using acme_certificate_dns_provider=ns1, the NS1 account key must be passed in this option.

Please note that NS1 support depends on the external module ns1_record. Please check out the documentation on how to install it.

When acme_certificate_verify_auth=false, this is not required when acme_certificate_dns_provider=ns1 and can be provided in other ways, for example with module defaults.

acme_certificate_ocsp_must_staple

boolean

Whether a certificate with the OCSP Must Staple extension is requested.

Choices:

  • false ← (default)

  • true

acme_certificate_privatekey_mode

string

Which file mode to use for the private key file.

Default value is '0600' (octal string), which means read- and writeable by the owner, but not accessible by anyone else (except possibly root).

Default: "0600"

acme_certificate_regenerate_private_keys

boolean

Whether to regenerate private keys.

It is recommended to regularly create new private keys instead of re-using the existing ones forever. The easiest way to ensure this is to simply regenerate them when the certificates are regenerated.

If you use public key pinning, make sure to set this to false!

Choices:

  • false

  • true ← (default)

acme_certificate_renewal_on_remaining_days

integer

added in felixfontein.acme 0.5.0

Only obtain a new certificate if the certificate does not yet exist, or if the certificate’s expiry date is less than acme_certificate_renewal_on_remaining_days days in the future.

acme_certificate_root_certificate

string

The root certificate for the ACME directory.

Default value is https://letsencrypt.org/certs/isrgrootx1.pem for the root certificate of Let’s Encrypt.

Default: "https://letsencrypt.org/certs/isrgrootx1.pem"

acme_certificate_root_certificate_for_verification

string

The root certificate to use for validating the ceritificate chain if acme_certificate_verify_certs=true.

If acme_certificate_root_certificate is set to https://letsencrypt.org/certs/trustid-x3-root.pem.txt, this should be set to https://letsencrypt.org/certs/isrgrootx1.pem to avoid validation failure as the TrustID root has by now expired.

By default uses the same value as acme_certificate_root_certificate.

acme_certificate_select_chain

list / elements=dictionary

Must be in the format described for the select_chain parameter of community.crypto.acme_certificate module.

Allows to select the certificate chain to be used; acme_certificate_root_certificate must be used in conjunction.

This can be used for example with Let’s Encrypt to select which root certificate to use. See the documentation for concrete examples how to choose between the Let’s Encrypt roots.

authority_key_identifier

string

Checks for the AuthorityKeyIdentifier extension. This is an identifier based on the private key of the issuer of the intermediate certificate.

The identifier must be of the form C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10.

issuer

dictionary

Allows to specify parts of the issuer of a certificate in the chain must have to be selected.

If acme_certificate_select_chain[].issuer is empty, any certificate will match.

An example value would be {"commonName": "My Preferred CA Root"}.

subject

dictionary

Allows to specify parts of the subject of a certificate in the chain must have to be selected.

If acme_certificate_select_chain[].subject is empty, any certificate will match.

An example value would be {"CN": "My Preferred CA Intermediate"}

subject_key_identifier

string

Checks for the SubjectKeyIdentifier extension. This is an identifier based on the private key of the intermediate certificate.

The identifier must be of the form A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1.

test_certificates

string

Determines which certificates in the chain will be tested.

all tests all certificates in the chain (excluding the leaf, which is identical in all chains).

first only tests the first certificate in the chain, i.e. the one which signed the leaf.

last only tests the last certificate in the chain, i.e. the one furthest away from the leaf. Its issuer is the root certificate of this chain.

Choices:

  • "first"

  • "last"

  • "all" ← (default)

acme_certificate_server_location

string

Location where .well-known/acme-challenge/ will be served from.

Default: "/var/www/challenges"

acme_certificate_terms_agreed

boolean

Whether the terms of services are accepted or not.

Usually needs to be set explicitly to true to allow creating an ACME account.

This is only used for ACME v2.

Choices:

  • false ← (default)

  • true

acme_certificate_use_sops_for_key

boolean

Use Mozilla sops to encrypt private key.

Needs .sops.yaml file inside the keys directory or somewhere up the directory chain.

Choices:

  • false ← (default)

  • true

acme_certificate_verify_auth

boolean

added in felixfontein.acme 0.6.0

Whether to check whether authentication credentials are provided as role arguments for the DNS modules.

When disabled, you can also use module default groups or environment variables to provide these credentials.

Choices:

  • false

  • true ← (default)

acme_certificate_verify_certs

boolean

Whether to try to validate the generated certificate chain or not.

Will use acme_certificate_root_certificate_for_verification for the root certificate, or if that is not set, use acme_certificate_root_certificate.

Choices:

  • false

  • true ← (default)

See Also

See also

community.crypto.openssl_privatekey

You can create ACME account keys with this module.

community.crypto.acme_account

You can manage ACME accounts with this module.

Authors

  • Felix Fontein (@felixfontein)