API-based enrollment

Follow these steps to get certificates from DigiCert® Trust Lifecycle Manager into your Puppet environment using the Trust Lifecycle Manager REST API. The issued certificate gets sent back in the API response in PEM-encoded X.509 format.

Before you begin

You need an API token for an active DigiCert ONE user or service user with access to Trust Lifecycle Manager and a user role of Manager or User and certificate manager. See API access for more details.

In Trust Lifecycle Manager, you need a certificate profile with the REST API enrollment method and 3rd Party app authentication method. Gather the following parameters from the profile details page to use when configuring the integration:

Profile ID: Get it from the GUID field or DigiCert ONE URL of the profile details page.
REST API endpoint (API KEY auth): Copy it from the REST URL dropdown at the top of the profile details page.

Integration workflow

Step 1: Download the integration sample files

To begin the process of API-based certificate enrollment using Puppet, you’ll need to download and extract the provided sample files, then move them into the appropriate Puppet environment directory. This setup ensures that Puppet can properly find and use the configuration files and modules.

Download the Puppet integration package to get the following environment files:
- production/data/certbot.yaml: Contains key-value pairs for Certbot configuration, such as email, domain, and ACME server details, used by Hiera for data lookups.
- production/environment.conf: Defines environment-specific settings, such as module paths and manifest locations, for the production environment.
- production/hiera.yaml: Configures Hiera, Puppet’s hierarchical data lookup tool, specifying the data sources and hierarchy for resolving configuration data.
- production/manifests/site.pp: The main manifest file for the production environment, defining node-specific configurations and including the necessary classes.
- production/modules/certbot/manifests/init.pp: Contains the definition of the Certbot class, including resource declarations and configurations for managing Certbot installations and certificates.
Copy the package contents to your Puppet environment directory.
```
 sudo -u puppet cp -r puppet-restapi-integration/production/* /etc/puppetlabs/code/environments/production/
```
Note
Copying the files as the puppet user ensures the files have the correct ownership and permissions.
- If the files were not copied as the puppet user, copy as root (sudo), and then adjust the ownership and permissions to ensure proper access:
```
 sudo chown -R puppet:puppet /etc/puppetlabs/code/environments/production/
```

Step 2: Configure Puppet manifests and hiera data

In this step, you will configure the necessary Puppet manifests and hiera data to set up the environment for requesting and managing SSL/TLS certificates using Certbot.

Navigate to the Puppet environment directory.

 cd /etc/puppetlabs/code/environments/production

Update the hiera.yaml file to specify certbot.yaml as the data file. The modified hiera.yaml should look like this:

 version: 5
defaults:
datadir: data
data_hash: yaml_data

hierarchy:
- name: "Certbot"
    path: "certbot.yaml"

In the data directory, open the certbot.yaml file and update the following key/value pairs:
- common::common_csr_file: Specify the path where the CSR needs to be stored.
- common::common_private_key_file: Specify the path where the private key needs to be stored.
- common::common_country: Specify the country name for the certificate subject.
- common::common_state: Specify the state name for the certificate subject.
- common::common_locality: Specify the locality name for the certificate subject.
- common::common_organization: Specify the organization name for the certificate subject.
- common::common_common_name: Specify the common name (domain) for the certificate.
- common::common_api_url: Specify the API URL provided by Trust Lifecycle Manager.
- common::common_api_key: Specify the API key provided by Trust Lifecycle Manager.
- common::common_profile_id: Specify the profile ID from your Trust Lifecycle Manager profile.
- common::common_seat_id: Specify the seat ID.

Important

The site.pp file located in the manifests directory of your Puppet environment uses a wildcard (default) node block. This means the certbot class is applied to all nodes by default.

Step 3: Request a certificate

To request a certificate from Trust Lifecycle Manager on a Puppet server, run the following command:

 sudo /opt/puppetlabs/bin/puppet apply /etc/puppetlabs/code/environments/production/manifests/site.pp

This command performs the following actions:

Reads the site.pp manifest, which includes the certbot class.
Applies the configurations defined in the certbot class from init.pp and then:
- Installs necessary packages (aptitude, dpkg-dev, openssl, jq).
- Installs required gems (msgpack, pson).
- Generates a Certificate Signing Request (CSR) and storing the private key.
- Sends the CSR to the specified API endpoint for certificate issuance.

What's next?

The requested certificate is sent back in PEM-encoded X.509 format in the response. Check the logs for the CSR generation and API request to ensure they were completed successfully. The logs are located in /tmp/:

CSR Generation Log: /tmp/csr_generation.log
API Request Log: /tmp/csr_request.log

The certificate also appears in the Trust Lifecycle Manager Inventory view so you can monitor it and set up notifications.

Note

Certbot automatically attempts to renew certificates before they expire. Ensure that the necessary cron jobs or systemd timers are set up to handle automatic renewals. This is typically handled by Certbot’s default installation but verify that it is configured properly.