ecs_certificate – Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API¶
New in version 2.9.
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¶
See Also¶
See also
- openssl_privatekey – Generate OpenSSL private keys
Can be used to create private keys (both for certificates and accounts).
- openssl_csr – Generate OpenSSL Certificate Signing Request (CSR)
Can be used to create a Certificate Signing Request (CSR).
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.
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.
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.
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.
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 it's Subject Distinguished Name use the
organization details associated with that client, rather than what is
in the CSR.
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
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 | Returned | Description |
|---|---|---|
|
backup_file
string
|
changed and if backup is true |
Name of backup file created for the certificate.
Sample:
/path/to/[email protected]:22~
|
|
backup_full_chain_file
string
|
changed and if backup is true and full_chain_path is set. |
Name of the backup file created for the certificate chain.
Sample:
/path/to/[email protected]:22~
|
|
cert_days
integer
|
success |
The number of days the certificate remains valid.
Sample:
253
|
|
cert_details
dictionary
|
success |
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.
|
|
cert_status
string
|
success |
The certificate status in ECS.
Current possible values (which may be expanded in the future) are:
ACTIVE, APPROVED, DEACTIVATED, DECLINED, EXPIRED, NA, PENDING, PENDING_QUORUM, READY, REISSUED, REISSUING, RENEWED, RENEWING, REVOKED, SUSPENDEDSample:
ACTIVE
|
|
filename
string
|
changed or success |
The destination path for the generated certificate.
Sample:
/etc/ssl/crt/www.ansible.com.crt
|
|
serial_number
integer
|
success |
The serial number of the issued certificate.
Sample:
1235262234164342
|
|
tracking_id
integer
|
success |
The tracking ID to reference and track the certificate in ECS.
Sample:
380079
|
Status¶
This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]
Authors¶
Chris Trufan (@ctrufan)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.