Horizon certificate retrieval module

Note

This module is part of the evertrust.horizon collection (version 2.0.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 evertrust.horizon.

To use it in a playbook, specify: evertrust.horizon.horizon_get_certificate.

Synopsis

  • Wait for and retrieve a certificate from an enrollment request.

  • Polling stops when the certificate is available, the timeout expires, or the request reaches a terminal status without a certificate.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

ca_bundle

path

Path of a CA bundle used to validate the Horizon instance SSL certificate.

client_cert

path

Path of a client certificate.

Required if you use certificate based authentication

client_key

path

Path to the private key used for client-certificate authentication.

Required if you use certificate based authentication.

Restrict access to the key and inventory configuration files.

connect_timeout

float

Maximum number of seconds to wait for the controller to establish a connection to Horizon.

Default: 10.0

endpoint

string / required

Your Horizon instance base endpoint.

It must include the protocol (https://) and no trailing slash nor path.

poll_interval

integer

Time between request-status checks, in seconds.

Must be greater than zero.

Default: 5

read_timeout

float

Maximum number of seconds to wait between response reads by the controller after connecting to Horizon.

Default: 60.0

request_id

string / required

Request ID returned by evertrust.horizon.horizon_request_enroll.

timeout

integer

Maximum total waiting time, in seconds.

Set to zero to wait indefinitely.

This is separate from the per-request read_timeout option.

Default: 0

x_api_id

string

Horizon identifier

Required if you use credentials authentication

x_api_key

string

Secret API key used for Horizon credential authentication.

Required if you use credentials authentication.

Store this value with Ansible Vault.

Tasks containing lookup expressions with this value should use no_log=true.

Notes

Note

  • The module fails when the request is denied, canceled, or fails.

  • A timeout value of 0 waits indefinitely.

Examples

- name: Wait up to five minutes for certificate issuance
  evertrust.horizon.horizon_get_certificate:
    request_id: "{{ enrollment_request.request_id }}"
    timeout: 300
    poll_interval: 5
  register: enrollment_result

- name: Wait for the approved certificate indefinitely
  evertrust.horizon.horizon_get_certificate:
    request_id: "{{ enrollment_request.request_id }}"
    timeout: 0
    poll_interval: 10
  register: enrollment_result

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

certificate

dictionary

The certificate that was generated for this request. This is only available after the request has been approved.

Returned: On successful certificate issuance

_id

string

Horizon internal ID.

Returned: If present

certificate

string

The certificate’s PEM-encoded content.

Returned: If present

contactEmail

string

The certificate’s contact email. It will be used to send notifications about the certificate’s expiration and revocation.

Returned: If present

crlSynchronized

boolean

Whether the certificate’s revocation status is synchronized with a CRL.

Returned: If present

discoveredTrusted

boolean

True if the certificate was discovered and issued by an existing trusted CA.

False if the certificate was discovered but not issued by a trusted CA.

Null if the certificate was not discovered.

Returned: If present

discoveryData

list / elements=dictionary

A list of metadata containing information on where the certificate was discovered.

Returned: Only if the certificate was discovered

hostnames

list / elements=string

The certificate’s hostnames (netscan only).

Returned: If present

ip

string

The certificate’s host IP address.

Returned: Always

operatingSystems

list / elements=string

The certificate’s host operating system (localscan only).

Returned: If present

paths

list / elements=string

The path to the certificate on the host machine (localscan only).

Returned: If present

sources

list / elements=string

Information on the type of discovery that discovered this certificate.

Returned: Always

tlsPorts

list / elements=dictionary

The ports on which the certificate is exposed for HTTPS connection.

Returned: If present

port

integer

The number of the port.

Returned: Always

version

string

Protocol version used.

Returned: Always

usages

list / elements=string

The path of the configuration files that were used to find the certificates.

Returned: If present

discoveryInfo

list / elements=dictionary

A list of metadata containing information on how and when the certificate was discovered.

Returned: If present

campaign

string

The discovery campaign’s name.

Returned: Always

identifier

string

Identifier of the user that discovered this certificate.

Returned: If present

lastDiscoveryDate

integer

When this certificate was discovered for the last time.

Returned: Always

dn

string

The certificate’s Distinguished Name.

Returned: If present

extensions

list / elements=dictionary

The certificate’s extensions.

Returned: If present

key

string

The extension’s type.

Returned: Always

value

string

The extension’s value.

Returned: Always

grades

list / elements=dictionary

The certificate’s grades for the enabled grading policies.

Returned: If present

grade

string

The grade awarded by the grading policy.

Returned: Always

name

string

The name of the grading policy.

Returned: Always

holderId

string

The certificate’s computed holder ID.

It counts similar certificates used simultaneously by the same holder.

Returned: If present

issuer

string

The certificate’s issuer Distinguished Name.

Returned: If present

keyType

string

The certificate’s key type.

Returned: If present

labels

list / elements=dictionary

The certificate’s labels.

Returned: If present

key

string

The label’s name.

Returned: Always

value

string

The label’s value.

Returned: Always

metadata

list / elements=dictionary

The certificate’s technical metadata used internally.

Returned: If present

key

string

The metadata name.

Returned: Always

value

string

The metadata value.

Returned: Always

module

string

The certificate’s module.

Returned: If present

notAfter

integer

The certificate’s expiration date in milliseconds since the epoch.

Returned: If present

notBefore

integer

The certificate’s start date in milliseconds since the epoch.

Returned: If present

owner

string

The certificate’s owner. This is a reference to a local identity identifier.

Returned: If present

profile

string

The certificate’s profile.

Returned: If present

publicKeyThumbprint

string

The certificate’s public key thumbprint.

Returned: If present

revocationDate

integer

The certificate’s revocation date in milliseconds since the epoch. This field is only present if the certificate is revoked.

Returned: If present

revocationReason

string

The certificate’s revocation reason.

Returned: If present

revoked

boolean

Whether the certificate is revoked.

Returned: If present

selfSigned

boolean

Whether the certificate is self-signed.

Returned: If present

serial

string

The certificate’s serial number.

Returned: If present

signingAlgorithm

string

The certificate’s signing algorithm.

Returned: If present

subjectAlternateNames

list / elements=dictionary

The certificate’s Subject Alternate Names.

Returned: If present

sanType

string

The type of the SAN.

Returned: Always

value

string

The value of the SAN.

Returned: Always

team

string

The certificate’s team, as a reference to a team identifier.

It determines certificate permissions and notification recipients.

Returned: If present

thirdPartyData

list / elements=dictionary

The certificate’s information about synchronization with Horizon supported third parties.

Returned: If present

connector

string

The third party connector name on which this certificate is synchronized.

Returned: Always

fingerprint

string

The fingerprint of this certificate on the third party.

Returned: If present

id

string

The ID of this certificate on the third party.

Returned: Always

pushDate

integer

The date when the certificate was pushed to this third party.

Returned: If present

removeDate

integer

The date when the certificate was removed from this third party (in case of revocation).

Returned: If present

thumbprint

string

The certificate’s thumbprint.

Returned: If present

triggerResults

list / elements=dictionary

The result of the execution of triggers on this certificate.

Returned: If present

detail

string

Contains details on this trigger’s execution.

Returned: If present

event

string

The event that triggered the trigger.

Returned: Always

lastExecutionDate

integer

The last time this trigger was executed for this certificate and this event.

Returned: Always

name

string

The name of the trigger that was executed.

Returned: Always

nextDelay

string

Time that will be waited between the two successive executions of this trigger.

Returned: If present

nextExecutionDate

integer

The next scheduled execution time for this trigger.

Returned: If present

retries

integer

The number of remaining tries before the trigger is abandoned.

Returned: If present

retryable

boolean

Is this trigger manually retryable.

Returned: Always

status

string

The status of the trigger after its execution.

Returned: Always

triggerType

string

The type of the trigger.

Returned: Always

chain

list / elements=dictionary

Certificate trust chain.

Returned: On successful certificate issuance

p12

string

Base64-encoded PKCS#12 archive returned for a centralized enrollment.

Returned: When the completed centralized enrollment includes a PKCS#12 archive

p12_password

string

Password protecting the returned PKCS#12 archive.

Returned: When the PKCS#12 archive is returned

request_id

string

ID of the enrollment request.

Returned: Always

status

string

Last enrollment request status observed before the module returns.

Depending on the Horizon version, intermediate statuses can include pending, approved, and in_progress.

Terminal statuses without a certificate include denied, canceled, and failed.

Returned: Always

Authors

  • Evertrust R&D (@EverTrust)