community.crypto.entrust_cagw_certificate module – Request SSL/TLS certificates with the Certificate Authority Gateway (CAGW) API
Note
This module is part of the community.crypto collection (version 2.17.0).
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.entrust_cagw_certificate.
Synopsis
Create, get, and take actions (Hold, Unhold, Revoke certificates) with the Certificate Authority Gateway (CAGW) API.
Requires credentials for calling the CAGW API.
Requirements
The below requirements are needed on the host that executes this module.
cryptography >= 1.6
Parameters
Parameter |
Comments |
|---|---|
reason has to be given for the action |
|
what action has to be taken on the certificate i.e. RevokeAction, HoldAction, UnholdAction Choices:
|
|
A list of additional email addresses to receive the delivery notice and expiry notification for the certificate. |
|
Path for the Client cert key issued by the same CA |
|
Path for the Client cert issued by the same CA |
|
path for CAGW api specification doc |
|
Unique id for the Certificate Authority |
|
Profile id for the Certificate Authority |
|
This parameter defines which CA type connected at the backend. Supported list of CAs include ECS, SM, PKIaaS, MSCA Choices:
|
|
Base-64 encoded Certificate Signing Request (CSR). csr is accepted without PEM formatting around the Base-64 string. If no csr is provided when request_type=new and enrollment_format=X509, the certificate will not be generated and module will be failed |
|
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) |
|
distinguished name used either for generation for CSR or given in the CAGW enrollment api when enrollment format is PKCS12 |
|
enrollment_format i.e. X509 or PKCS12 Choices:
|
|
If force is used, a certificate is requested regardless of whether path points to an existing valid certificate. Choices:
|
|
Host or IP address for Entrust CAGW. |
|
p12 password for server side generation of the private key and CSR |
|
The destination path for the generated certificate as a PEM encoded cert. If there is already an Entrust certificate at this location, it will be replaced always. If |
|
port for Entrust CAGW Default: |
|
The number of days the certificate must have left being valid. If The force option may be used to ensure that a new certificate is always obtained. Default: |
|
request type i.e. new (stands for enrollment), get (stands for get certificate), action (stands for action to be taken on the certificate) 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. |
|
serial number of the already issued certificate |
|
The subject alternative name identifiers, |
|
directoryName of the target server |
|
DNS name of the target server |
|
ip address of the target server |
|
rfc822 name of the target server |
|
URI of the target server |
|
Free form tracking information to attach to the record for the certificate. |
|
if set to false then Server validation is skipped Choices:
|
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).
Examples
- name: Request a new certificate from SM via CAGW with bare minimum parameters. Will request a new certificate
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
certificate_profile_id: profile_id
request_type: new
enrollment_format: X509
connector_name: SM
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
- name: Request a new certificate from CAGW with subjectAltName parameters and server cert validation is false
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
certificate_profile_id: profile_id
request_type: new
enrollment_format: X509
connector_name: SM
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
subject_alt_name:
dNSName: server.example.com
iPAddress: 192.168.1.1
directoryName: cn=john doe,o=example inc,c=us
uniformResourceIdentifier: http://example.com/
rfc822Name: server.example.com
validate_certs: False
- name: Get an already issued certificate from CAGW with valid serial num in hexadecimal format
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
request_type: get
serial_no: 5b9ba13d
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
- name: Request a certificate from CAGW with enrollment format PKCS12
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
certificate_profile_id: profile_id
request_type: new
enrollment_format: PKCS12
connector_name: SM
p12_protection_password: 'Entrust@2018'
dn: /C=CA/O=iotrust/CN=CA/CN=ans-test-anurag-101
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
- name: Request a new SSL certificate from ECS via CAGW with bare minimum parameters. Will request a new certificate
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
certificate_profile_id: profile_id
request_type: new
enrollment_format: X509
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
connector_name: ECS
requester_name: Sapna-CAGW-server
requester_email: sapna.jain@entrustdatacard.com
requester_phone: 613-222-2222
- name: Request a new SSL certificate from ECS via CAGW with optional custom_field parameters. Will request a new certificate
community.crypto.entrust_cagw_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
certificate_profile_id: profile_id
request_type: new
enrollment_format: X509
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
connector_name: ECS
requester_name: Sapna-CAGW-server
requester_email: sapna.jain@entrustdatacard.com
requester_phone: 613-222-2222
custom_fields:
text1: Admin
text2: Invoice 25
number1: 342
date1: '2018-01-01'
email1: sales@ansible.testcertificates.com
dropdown1: red
- name: Take an action(HoldAction) on certificate already recieved from CAGW
community.crypto.entrust_cagw_certificate:
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
request_type: action
action_type: HoldAction
action_reason: unspecified
serial_no: 5b9ba13d
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
- name: Take an action(UnholdAction) on certificate already recieved from CAGW
community.crypto.entrust_cagw_certificate:
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
request_type: action
action_type: UnholdAction
action_reason: unspecified
serial_no: 5b9ba13d
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
- name: Take an action(RevokeAction) on certificate already recieved from CAGW
community.crypto.entrust_cagw_certificate:
cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
certificate_authority_id: ca_id
request_type: action
action_type: RevokeAction
action_reason: unspecified
serial_no: 5b9ba13d
cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The number of days the certificate remains valid. Returned: success Sample: |
|
The full response JSON from the New/Get Certificate call of the CAGW API. While the response contents are guaranteed to be forwards compatible with new CAGW 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 CAGW. Possible values are: ACCEPTED, normal, Revoked, Held Returned: success |
|
The destination path for the generated certificate or PKCS12. Returned: changed or success Sample: |
|
Message we get from CAGW. Returned: success |
|
The serial number of the issued certificate. Returned: success Sample: |
Authors
Sapna Jain (@jains)