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
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/
Aviso
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/
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 specifycertbot.yaml
as the data file. The modifiedhiera.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.
Importante
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.
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 thecertbot
class.Applies the configurations defined in the
certbot
class frominit.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.
Aviso
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.