ecs_certificate – Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API
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
| Parameter | Choices/Defaults | Comments | |
|---|---|---|---|
|
additional_emails list / elements=string |
A list of additional email addresses to receive the delivery notice and expiry notification for the certificate. | ||
|
backup boolean |
|
Whether a backup should be made for the certificate in path. | |
|
cert_expiry string |
The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example, cert_expiry is only supported for requests of 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 cert_expiry or cert_lifetime may be specified. | ||
|
cert_lifetime string |
|
The lifetime of the certificate. Applies to all certificates for accounts with a non-pooling inventory model. cert_lifetime is only supported for requests of Applies to certificates of cert_type=
Only one of cert_expiry or cert_lifetime may be specified. | |
|
cert_type string |
|
Specify the type of certificate requested. If a certificate is being reissued or renewed, this parameter is ignored, and the | |
|
client_id integer |
Default: 1 |
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 org parameter cannot be specified. The issued certificate will have an organization value in the subject distinguished name represented by the client. | |
|
csr string |
Base-64 encoded Certificate Signing Request (CSR). csr is accepted with or without PEM formatting around the Base-64 string. If no csr is provided when If subject_alt_name is specified, it will override the subject alternate names in the CSR. If eku is specified, it will override the extended key usage in the CSR. If ou is specified, it will override the organizational units "ou=" present in the subject distinguished name of the CSR, if any. The organization "O=" field from the CSR will not be used. It will be replaced in the issued certificate by org if present, and if not present, the organization tied to client_id. | ||
|
ct_log boolean |
|
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 ct_log is not specified, the certificate uses the account default. If ct_log is specified and the account settings allow it, ct_log overrides the account default. If ct_log is set to | |
|
custom_fields dictionary |
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. | ||
|
date1 string |
Custom date field. | ||
|
date2 string |
Custom date field. | ||
|
date3 string |
Custom date field. | ||
|
date4 string |
Custom date field. | ||
|
date5 string |
Custom date field. | ||
|
dropdown1 string |
Custom dropdown field. | ||
|
dropdown2 string |
Custom dropdown field. | ||
|
dropdown3 string |
Custom dropdown field. | ||
|
dropdown4 string |
Custom dropdown field. | ||
|
dropdown5 string |
Custom dropdown field. | ||
|
email1 string |
Custom email field. | ||
|
email2 string |
Custom email field. | ||
|
email3 string |
Custom email field. | ||
|
email4 string |
Custom email field. | ||
|
email5 string |
Custom email field. | ||
|
number1 float |
Custom number field. | ||
|
number2 float |
Custom number field. | ||
|
number3 float |
Custom number field. | ||
|
number4 float |
Custom number field. | ||
|
number5 float |
Custom number field. | ||
|
text1 string |
Custom text field (maximum 500 characters) | ||
|
text10 string |
Custom text field (maximum 500 characters) | ||
|
text11 string |
Custom text field (maximum 500 characters) | ||
|
text12 string |
Custom text field (maximum 500 characters) | ||
|
text13 string |
Custom text field (maximum 500 characters) | ||
|
text14 string |
Custom text field (maximum 500 characters) | ||
|
text15 string |
Custom text field (maximum 500 characters) | ||
|
text2 string |
Custom text field (maximum 500 characters) | ||
|
text3 string |
Custom text field (maximum 500 characters) | ||
|
text4 string |
Custom text field (maximum 500 characters) | ||
|
text5 string |
Custom text field (maximum 500 characters) | ||
|
text6 string |
Custom text field (maximum 500 characters) | ||
|
text7 string |
Custom text field (maximum 500 characters) | ||
|
text8 string |
Custom text field (maximum 500 characters) | ||
|
text9 string |
Custom text field (maximum 500 characters) | ||
|
eku string |
|
If specified, overrides the key usage in the csr. | |
|
end_user_key_storage_agreement boolean |
|
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 cert_type of values | |
|
entrust_api_client_cert_key_path path / required |
The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. | ||
|
entrust_api_client_cert_path path / required |
The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. | ||
|
entrust_api_key string / required |
The key (password) for authentication to the Entrust Certificate Services (ECS) API. | ||
|
entrust_api_specification_path path |
Default: |
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. | |
|
entrust_api_user string / required |
The username for authentication to the Entrust Certificate Services (ECS) API. | ||
|
force boolean |
|
If force is used, a certificate is requested regardless of whether path points to an existing valid certificate. If | |
|
full_chain_path path |
The destination path for the full certificate chain of the certificate, intermediates, and roots. | ||
|
org string |
Organization "O=" to include in the certificate. If org is not specified, the organization from the client represented by client_id is used. Unless the cert_type is | ||
|
ou list / elements=string |
Organizational unit "OU=" to include in the certificate. ou behavior is dependent on whether organizational units are enabled for your account. If organizational unit support is disabled for your account, organizational units from the csr and the ou parameter are ignored. If both csr and ou are specified, the value in ou will override the OU fields present in the subject distinguished name in the csr If neither csr nor ou are specified for a renew or reissue operation, the OU fields in the initial certificate are reused. An invalid OU from csr is ignored, but any invalid organizational units in ou will result in an error indicating "Unapproved OU". The ou parameter can be used to force failure if an unapproved organizational unit is provided. A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products. | ||
|
path path / required |
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 remaining_days calculation. If an existing certificate is being replaced (see remaining_days, force, and tracking_id), whether a new certificate is requested or the existing certificate is renewed or reissued is based on request_type. | ||
|
remaining_days integer |
Default: 30 |
The number of days the certificate must have left being valid. If If The force option may be used to ensure that a new certificate is always obtained. | |
|
request_type string |
|
The operation performed if tracking_id references a valid certificate to reissue, or there is already a certificate present in path but either force is specified or Specifying Specifying Specifying Specifying If a certificate was issued within the past 30 days, the 'renew' operation is not a valid operation and will fail. Note that check_mode is only supported if For example, setting | |
|
requester_email string / required |
The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. | ||
|
requester_name string / required |
The requester name to associate with certificate tracking information. | ||
|
requester_phone string / required |
The requester phone number to associate with certificate tracking information. | ||
|
subject_alt_name list / elements=string |
The subject alternative name identifiers, as an array of values (applies to cert_type with a value of If you are requesting a new SSL certificate, and you pass a subject_alt_name parameter, any SAN names in the CSR are ignored. If no subjectAltName parameter is passed, the SAN names in the CSR are used. See request_type to understand more about SANs during reissues and renewals. In the case of certificates of type | ||
|
tracking_id integer |
The tracking ID of the certificate to reissue or renew. tracking_id is invalid if If there is a certificate present in path and it is an ECS certificate, tracking_id will be ignored. If there is no certificate present in path or there is but it is from another provider, the certificate represented by tracking_id will be renewed or reissued and saved to path. If there is no certificate present in path and the force and remaining_days parameters do not indicate a new certificate is needed, the certificate referenced by tracking_id certificate will be saved to path. 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 | ||
|
tracking_info string |
Free form tracking information to attach to the record for the certificate. |
Notes
Note
pathmust be specified as the output location of the certificate.
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.keyReturn 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/www.ansible.com.crt.2019-03-09@11: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/ca.chain.crt.2019-03-09@11: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:
Sample: 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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/ecs_certificate_module.html
