Automation

The Horizon Client can help you automate the installation of your TLS certificates. This page documents both the legacy automation module, as it was in the 1.5.x series, and the new automation module, which is available in the 1.6.x series.

Legacy Automation

The legacy automation is now deprecated. Please use the New Automation instead

Microsoft IIS

The automate command for Microsoft IIS will enroll or renew a certificate, store it in the Windows Machine Store using the software backend, and bind it to the specified host and port.

horizon-cli automate iis --enroll=<challenge> --profile=myestprofile --dnsnames=www.example.com --bind-host www.example.com:443

Apache

The automate command for Apache works exactly the same as the est client, except that it will restart your Apache server after the certificate has been installed.

To restart your server, the client will try to use the service command to restart the service named httpd if the client is run on a RHEL machine or apache2 if any other distibution is used.

 
horizon-cli automate apache --enroll=<challenge> --profile=myestprofile --dnsnames=www.example.com --cert /etc/ssl/certs/apache.pem --key /etc/ssl/private/apache.key

Nginx

The automate command for Nginx works exactly the same as the est client, except that it will restart your Nginx server after the certificate has been installed.

To restart your server, the client will try to use the service command to restart the service named nginx.

 
horizon-cli automate nginx --enroll=<challenge> --profile=myestprofile --dnsnames=www.example.com --cert /etc/ssl/certs/nginx.pem --key /etc/ssl/private/nginx.key

New Automation

The automate enroll command is the entry point for the new automation module. The difference between the legacy and new automation module resides in the discovery of certificates on your machine, and on the automatic renewal.

Automation policies

The new automation module relies on automation policies to know how the certificates should be enrolled and renewed. Automation policies are configurable in the Horizon web app, contain an EST, SCEP or ACME profile and other options, like preferred enrollment CA and hash algorithm. For each automation operation, an automation policy needs to be specified using the --automation-policy parameter.

EverTrust recommends using EST for most use cases of server automation.
SCEP automation is not yet supported on windows servers.

Discovery

The new automation module will discover certificates on your machine by parsing your webserver’s or TLS service’s configuration files. Supported services are:

  • apache

  • nginx

  • tomcat

  • jboss wildfly

  • lighttpd

  • microsoft iis

  • winhorizon

  • horizon adcsconnector

By default, the automate enroll command will try to search for all supported services. If you want to limit the search to a specific list of services, you can use the --target option.

horizon-cli automate enroll --target=apache,nginx [...]

The discovery of config files relies on the "usual" locations for the services configuration folder. If you have an "unusual" configuration folder for your service, you can use the --config-folder option to specify it. Note that it only works if you restrict the discovery to a single service.

You can use the --analyze-only flag to only perform the discovery phase, print results and exit.

Enrollment

Once the discovery phase is done, you will be presented with a list of certificates that can be enrolled. You can then select the certificates you want to enroll, and enrollments will be performed according to the automation policy and it’s corresponding profile.

For example, if your automation policy specifies an EST profile with challenge password validation, the client will enroll the certificate using the EST protocol, and you will be prompted for the challenge password.

The enrollment is meant to be somewhat intelligent, in that it does not enroll certificates that are already known by Horizon and compliant to your automation policy. For example, if you have initially enrolled your web server’s certificate using the EST, SCEP or ACME client on the same profile, and you run the automate enroll command, the client will not try to enroll the certificate again, but will simply update its internal database with the new information. If you want to re-enroll the certificates anyway, you can use the --force-enroll option.

Additional enrollment parameters

You can chain a certificate enrollment operation with the discovery operation by using the --discovery parameter to specify your discovery campaign. It will use the APIID and APIKEY defined in the general configuration to authenticate to Horizon and feed it with the enrolled certificate and its discovery metadata. Upon enrollment, you can add additional metadata to the certificate using the following parameters:

Table 1. Metadata parameters
Parameter Description

--owner

Owner of the certificate

--contact-email

Contact email of the certificate owner

--team

Team owning the certificate

--labels

Labels to attach to the certificate, in the form key:value

Installation

After a successful enrollment or renewal, the certificate will be installed on your machine. The installation process will depend on the services that use the certificate, and the storage backend that was used to store the certificate. For example, if the certificate was used by Tomcat and was stored as a PKCS#12 file, then this file will be overwritten, with the same password. The old PKCS#12 file will be backed up by the client.

The impacted services will be restarted automatically after each certificate enrollment or renewal.

If you wish for the client to not install your new certificate, that is, not replace the old certificate and not restart the impacted services, you can use the --no-install option. Each new file (cert, key, CA chain, keystore…​) will then be placed in the same folder as it’s predecessor, with the .new extension.

Renewal

Each time a certificate is discovered and enrolled by the automation module of the Horizon Client, its details are stored in the internal database for future reference. Each time the automate routine command is run, the client will check if any of the locally known certificates need to be renewed. Reasons for renewal can be:

  • The certificate is about to expire

  • The certificate has been revoked

  • Preferences such as key type or enrollment CA were changed in the profile or automation policy

If a certificate needs to be renewed, the client will perform the renewal according to the automation policy, and its corresponding profile.

We recommend that you run the automate routine command periodically as a cron job or scheduled task. You can use the command horizon-cli automate create-periodic-task <period> or the flag --auto-renew on the automate enroll command to help you in the process, or create it manually.

This mechanism allows for more resilient web servers, as the certificates will be renewed automatically, before any interruption of service can happen because of an expired or revoked certificate. It also helps your organisation migrate your TLS certificates to a new CA quickly, by simply changing the preferred enrollment CA in the automation policy and waiting a few hours for all your instances of the Horizon Client to execute their routine tasks.

Backup

Each time a file is replaced by the Horizon Client, the old file is backed up. The backup files are stored in the cert/backup/<HASH(BACKUPED FILE PATH)> directory relative to the Horizon Client data folder (/opt/horizon on unix and C:/ProgramData/EverTrust/Horizon on Windows), as filename_n.ext where n is the number of the backup. Thus, the filename_0.ext is the original version, before any intervention of the Horizon Client.

Internal Database operations

The internal database is used to store the details of the certificates that are discovered and enrolled by the automation module. You can list them using the automate list command, and delete them using the automate delete command. Certificates are indexed by their bindings, which are the combination of all the services along with the hostnames and ports that use the certificate. For example, if you have a certificate that is used by Apache for all hosts on the port 443, it’s "id" in the local database will be apache-*:443. We found this to be a human-readable way of uniquely identifying a local certificate.

You can choose the output format of the automate list command. By default it outputs a string, but you can use the --json option to output a JSON object. example:

horizon-cli automate list --json | jq

The automate remove <id1> …​ <idn> command erases certificates from the local database. This command will not remove the certificate files from your machine, only remove it from the "managed certificates" local database. This way, the client will not check its status at each routine execution anymore.

You can use the automate remove all command to remove all certificates from the local database.

The --restore option of the automate remove command can be used to restore a certificate from a backup file. The backup file to be restored will always be the older one, in most cases the filename_0.ext, that is, the original file before any tampering by the Horizon Client.

Interactivity

Two options are available to control the interactivity of the automate enroll command:

  • The --no-interactive flag will prevent any prompt from being displayed, and will use the default values or those provided in the command line arguments. It will:

    • select all discovered certificates for enrollment

    • if a challenge is required, use the provided --challenge argument. If no challenge is provided, or the given challenge has already been used, the enrollment will fail.

    • not add any additional SANs

  • the --prompt flag will force the client to prompt the user for any missing information. If specified, any other command line arguments are optional. It will:

    • prompt the user to select which services to search for on the machine (equivalent to the --target option)

    • prompt the user for the automation policy (equivalent to the --automation-policy option)

Examples

Enroll certificates used by nginx and apache

horizon-cli automate enroll \
  --target=nginx,apache \
  --automation-policy=MyPolicy

Use the interactive mode

horizon-cli automate enroll --prompt

Check if the previously enrolled certificates need to be renewed

horizon-cli automate routine

Get the DN of all the certificates enrolled by the automation module

hzn automate list --json | jq -r '.[] | .certificate | .subject'

Remove the certificate used by nginx on the port 443 from the automatically renewed certificates

horizon-cli automate remove nginx-*:443