community.crypto.ecs_certificate module – Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API
Note
This module is part of the community.crypto collection (version 2.26.5).
You might already have this collection installed if you are using the ansible package.
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 community.crypto.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.crypto.ecs_certificate.
Synopsis
Create, reissue, and renew certificates with the Entrust Certificate Services (ECS) API.
Requires credentials for the Entrust Certificate Services (ECS) API.
In order to request a certificate, the domain and organization used in the certificate signing request must be already validated in the ECS system. It is not the responsibility of this module to perform those steps.
Requirements
The below requirements are needed on the host that executes this module.
PyYAML >= 3.11
cryptography >= 1.6
Parameters
Parameter |
Comments |
|---|---|
A list of additional email addresses to receive the delivery notice and expiry notification for the certificate. |
|
The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
A reissued certificate will always have the same expiry as the original certificate. Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an expiry time with the expiry date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous day. Applies only to accounts with a pooling inventory model. Only one of |
|
The lifetime of the certificate. Applies to all certificates for accounts with a non-pooling inventory model.
Applies to certificates of
Only one of Choices:
|
|
Specify the type of certificate requested. If a certificate is being reissued or renewed, this parameter is ignored, and the Choices:
|
|
The client ID to submit the Certificate Signing Request under. If no client ID is specified, the certificate will be submitted under the primary client with ID of 1. When using a client other than the primary client, the The issued certificate will have an organization value in the subject distinguished name represented by the client. Default: |
|
Base-64 encoded Certificate Signing Request (CSR). If no If If If The organization “O=” field from the CSR will not be used. It will be replaced in the issued certificate by |
|
In compliance with browser requirements, this certificate may be posted to the Certificate Transparency (CT) logs. This is a best practice technique that helps domain owners monitor certificates issued to their domains. Note that not all certificates are eligible for CT logging. If If If Choices:
|
|
Mapping of custom fields to associate with the certificate request and certificate. Only supported if custom fields are enabled for your account. Each custom field specified must be a custom field you have defined for your account. |
|
Custom date field. |
|
Custom date field. |
|
Custom date field. |
|
Custom date field. |
|
Custom date field. |
|
Custom dropdown field. |
|
Custom dropdown field. |
|
Custom dropdown field. |
|
Custom dropdown field. |
|
Custom dropdown field. |
|
Custom email field. |
|
Custom email field. |
|
Custom email field. |
|
Custom email field. |
|
Custom email field. |
|
Custom number field. |
|
Custom number field. |
|
Custom number field. |
|
Custom number field. |
|
Custom number field. |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
Custom text field (maximum 500 characters). |
|
If specified, overrides the key usage in the Choices:
|
|
The end user of the Code Signing certificate must generate and store the private key for this request on cryptographically secure hardware to be compliant with the Entrust CSP and Subscription agreement. If requesting a certificate of type Applicable only to Choices:
|
|
The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. |
|
The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. |
|
The key (password) for authentication to the Entrust Certificate Services (ECS) API. |
|
The path to the specification file defining the Entrust Certificate Services (ECS) API configuration. You can use this to keep a local copy of the specification to avoid downloading it every time the module is used. Default: |
|
The username for authentication to the Entrust Certificate Services (ECS) API. |
|
If force is used, a certificate is requested regardless of whether If Choices:
|
|
The destination path for the full certificate chain of the certificate, intermediates, and roots. |
|
Organization “O=” to include in the certificate. If Unless the |
|
Organizational unit “OU=” to include in the certificate.
If both If neither An invalid OU from A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products. |
|
The destination path for the generated certificate as a PEM encoded cert. If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested even if the current certificate is technically valid. If there is already an Entrust certificate at this location, whether it is replaced is depends on the If an existing certificate is being replaced (see |
|
The number of days the certificate must have left being valid. If If For example, if you are requesting Certificates with a 90 day lifetime, do not set The Default: |
|
The operation performed if Specifying Specifying Specifying Specifying If a certificate was issued within the past 30 days, the Note that check_mode is only supported if For example, setting Choices:
|
|
The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. |
|
The requester name to associate with certificate tracking information. |
|
The requester phone number to associate with certificate tracking information. |
|
The subject alternative name identifiers, as an array of values (applies to If you are requesting a new SSL certificate, and you pass a See In the case of certificates of type |
|
The tracking ID of the certificate to reissue or renew.
If there is a certificate present in If there is no certificate present in If there is no certificate present in This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it to be managed by an ansible playbook. For example, if you specify |
|
Free form tracking information to attach to the record for the certificate. |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: partial Check mode is only supported if |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
|
Support: partial The module is not idempotent if Under which conditions the module is idempotent still needs to be determined. If you are using this module and have more information, please contribute to the documentation! |
When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. This assumes that the system controlled/queried by the module has not changed in a relevant way. |
|
Support: full |
Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. |
Notes
Note
pathmust be specified as the output location of the certificate.
See Also
See also
- community.crypto.openssl_privatekey
Can be used to create private keys (both for certificates and accounts).
- community.crypto.openssl_csr
Can be used to create a Certificate Signing Request (CSR).
- community.crypto.to_serial filter plugin
Convert an integer to a colon-separated list of hex numbers.
Examples
---
- name: Request a new certificate from Entrust with bare minimum parameters. Will request a new certificate if current one
is valid but within 30 days of expiry. If replacing an existing file in path, will back it up.
community.crypto.ecs_certificate:
backup: true
path: /etc/ssl/crt/ansible.com.crt
full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
csr: /etc/ssl/csr/ansible.com.csr
cert_type: EV_SSL
requester_name: Jo Doe
requester_email: [email protected]
requester_phone: 555-555-5555
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: If there is no certificate present in path, request a new certificate of type EV_SSL. Otherwise, if there is an
Entrust managed certificate in path and it is within 63 days of expiration, request a renew of that certificate.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
cert_type: EV_SSL
cert_expiry: '2020-08-20'
request_type: renew
remaining_days: 63
requester_name: Jo Doe
requester_email: [email protected]
requester_phone: 555-555-5555
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: If there is no certificate present in path, download certificate specified by tracking_id if it is still valid.
Otherwise, if the certificate is within 79 days of expiration, request a renew of that certificate and save it in path.
This can be used to "migrate" a certificate to be Ansible managed.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
tracking_id: 2378915
request_type: renew
remaining_days: 79
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Force a reissue of the certificate specified by tracking_id.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
force: true
tracking_id: 2378915
request_type: reissue
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request a new certificate with an alternative client. Note that the issued certificate will have its Subject Distinguished
Name use the organization details associated with that client, rather than what is in the CSR.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
client_id: 2
requester_name: Jo Doe
requester_email: [email protected]
requester_phone: 555-555-5555
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request a new certificate with a number of CSR parameters overridden and tracking information
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
csr: /etc/ssl/csr/ansible.com.csr
subject_alt_name:
- ansible.testcertificates.com
- www.testcertificates.com
eku: SERVER_AND_CLIENT_AUTH
ct_log: true
org: Test Organization Inc.
ou:
- Administration
tracking_info: "Submitted via Ansible"
additional_emails:
- [email protected]
- [email protected]
custom_fields:
text1: Admin
text2: Invoice 25
number1: 342
date1: '2018-01-01'
email1: [email protected]
dropdown1: red
cert_expiry: '2020-08-15'
requester_name: Jo Doe
requester_email: [email protected]
requester_phone: 555-555-5555
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Name of backup file created for the certificate. Returned: changed and if Sample: |
|
Name of the backup file created for the certificate chain. Returned: changed and if Sample: |
|
The number of days the certificate remains valid. Returned: success Sample: |
|
The full response JSON from the Get Certificate call of the ECS API. While the response contents are guaranteed to be forwards compatible with new ECS API releases, Entrust recommends that you do not make any playbooks take actions based on the content of this field. However it may be useful for debugging, logging, or auditing purposes. Returned: success |
|
The certificate status in ECS. Current possible values (which may be expanded in the future) are: Returned: success Sample: |
|
The destination path for the generated certificate. Returned: changed or success Sample: |
|
The serial number of the issued certificate. This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success Sample: |
|
The tracking ID to reference and track the certificate in ECS. Returned: success Sample: |