Horizon enrollment plugin

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. You need further requirements to be able to use this module, see Requirements for details.

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

Synopsis

  • Performs an enrollment against the Horizon API.

Note

This module has a corresponding action plugin.

Requirements

The below requirements are needed on the host that executes this module.

  • cryptography>=3.4.0

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

contact_email

string

Certificate’s contact email.

Default value will be the requester contact email address.

csr

any

A certificate signing request, or the path to the CSR file.

If none is provided, one will be generated on-the-fly.

src

path

The path to a CSR file.

endpoint

string / required

Your Horizon instance base endpoint.

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

key_type

string

Key type to use when generating a key pair.

If omitted, the default key type from the certificate profile is used.

Choices:

  • "rsa-2048"

  • "rsa-3072"

  • "rsa-4096"

  • "ec-secp256r1"

  • "ec-secp384r1"

labels

dictionary

Certificate’s labels.

metadata

dictionary

Certificate metadata as key-value pairs.

mode

string

Enrollment mode.

If empty, will be inferred from the Horizon certificate profile configuration.

Choices:

  • "centralized"

  • "decentralized"

owner

string

Certificate’s owner.

password

string

Security password for the certificate.

Password policies will be applied to check validity.

Required only if the enrollment is centralized and the password generation mode is not random.

Can also be required if the profile allows both centralized and decentralized enrollment with manual password generation.

In that case, a password is necessary for decentralized enrollment.

profile

string / required

Name of the profile that will be used to enroll the certificate.

read_timeout

float

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

Default: 60.0

sans

dictionary

Certificate’s subject alternative names (SANs) of the certificate.

Authorized values are: [dnsname, rfc822name, ipaddress, othername_upn, othername_guid, uri].

subject

dictionary / required

Certificate’s subject.

You can either give the description of the subject, or the full DN.

If you give the DN, other values won’t be used.

team

string

Certificate’s team.

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

  • Enrolling a certificate requires permissions on the related profile.

  • Be sure to use the “Enroll API” permission instead of “Enroll”.

Examples

- name: Enrolling a certificate in a centralized way
  evertrust.horizon.horizon_enroll:
    endpoint: "https://<horizon-endpoint>"
    x_api_id: "<horizon-id>"
    x_api_key: "<horizon-password>"
    mode: "centralized"
    password: "examplePassword"
    key_type: "rsa-2048"
    profile: "exampleProfile"
    subject:
      cn.1: "exampleCN"
    sans:
      dnsname: "exampleDnsname"
    labels:
      snow_id: "value1"
      exp_tech: "value2"

- name: Enrolling a certificate in a decentralized way with a CSR
  evertrust.horizon.horizon_enroll:
    endpoint: "https://<horizon-endpoint>"
    x_api_id: "<horizon-id>"
    x_api_key: "<horizon-password>"
    mode: "decentralized"
    csr: |
      -----BEGIN CERTIFICATE REQUEST-----
      // Content
      -----END CERTIFICATE REQUEST-----
    password: "examplePassword"
    key_type: "rsa-2048"
    profile: "exampleProfile"
    subject:
      cn.1: "exampleCN"
      ou.1: "exampleFirstOU"
      ou.2: "exampleSecondOU"
    sans:
      dnsname:
        - "exampleDnsName1"
        - "exampleDnsName2"
    labels:
      snow_id: "value1"
      exp_tech: "value2"

- name: Enrolling a certificate in a decentralized way with CSR file
  evertrust.horizon.horizon_enroll:
    endpoint: "https://<horizon-endpoint>"
    x_api_id: "<horizon-id>"
    x_api_key: "<horizon-password>"
    mode: "decentralized"
    csr:
      src: "/the/path/to/my/CSR.csr"
    password: "examplePassword"
    key_type: "rsa-2048"
    profile: "exampleProfile"
    subject:
      cn.1: "exampleCN"
      ou:
        - "exampleFirstOU"
        - "exampleSecondOU"
    sans:
      dnsname: "exampleDnsName"
    labels:
      label1: "value1"
      label2: "value2"

Return Values

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

Key

Description

certificate

dictionary

The certificate generated by the enrollment.

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’s trust chain.

Returned: When the certificate is returned

key

string

Certificate’s private key.

Returned: If enrollment mode is “centralized” or if a key pair was generated on-the-fly

p12

string

Base64-encoded PKCS#12

Returned: If enrollment mode is “centralized” or if a key pair was generated on-the-fly

p12_password

string

PKCS#12 password.

Returned: If enrollment mode is “centralized” or if a key pair was generated on-the-fly

Authors

  • Evertrust R&D (@EverTrust)