Set up managed automation for custom applications

DigiCert® Trust Lifecycle Manager's managed automation solution supports the most popular web server applications out of the box.

DigiCert also provides the flexibility to extend certificate management for applications not natively supported by allowing the use of third-party ACME clients through custom automation scripts.

Follow these steps to enable managed automation of certificates for a custom application:

Deploy DigiCert agent
Install and configure a DigiCert agent on the server system. The agent coordinates automation requests sent from Trust Lifecycle Manager.
Set up third-party ACME client
Install and configure your preferred third-party ACME client on the server system. The third-party ACME client does the work of procuring and installing certificates for the custom application.
Create shell script
Create a shell script for the local DigiCert agent to use to invoke the third-party ACME client on the server system. Store this custom automation script in the DigiCert agent's packages sub-directory.
Add script details in Trust Lifecycle Manager
Configure the shell script details in Trust Lifecycle Manager so it knows how to find and execute the custom automation script.
Assign script to the applicable agent IP/port targets
Configure the agent in Trust Lifecycle Manager so it knows the IP/port targets where the custom application is running.

Deploy DigiCert agent

Custom automations require that a DigiCert agent be installed and running on each server. The agent coordinates automation requests received from Trust Lifecycle Manager and calls your custom shell script to handle certificate lifecycle events for the custom application.

For detailed instructions about setting up a DigiCert agent, see Deploy and manage agents.

Set up third-party ACME client

You can use any third-party ACME client compliant with the ACME v2 protocol to set up custom automations on your servers.

Follow the software provider's guidelines to install and configure your preferred third-party ACME client on the local server system.

Create shell script

You need a custom shell script to drive the third-party ACME client on your server. During an automation event, the DigiCert agent calls this shell script to invoke the ACME client, which then procures and installs the certificate.

The shell script must contain the basic automation commands for the third-party ACME client. Command syntax varies depending on which third-party ACME client is used. Check the software provider's guidelines to learn more.

Below are examples of shell scripts used to get DigiCert® certificates via third-party clients Certbot (Linux) and Win-ACME (Windows):

Example 1. Certbot (Linux)

directoryuri=$1
host=$2
emailaddress=$3
eabkeyidentifier=$5
eabkeyhmac=$6
process_path=/usr/bin/apachectl
server_root=/etc/httpd
config_root=/etc/httpd/config
procCmdLine="/usr/bin/apachectl start"
acmeConfigDirectory="/etc/letsencrypt/"
certbot --server $directoryuri --config-dir $acmeConfigDirectory --eab-kid $eabkeyidentifier  --eab-hmac-key $eabkeyhmac --installer apache -m $emailaddress --force-renew --agree-tos --no-redirect --expand -d $host --no-verify-ssl --no-autorenew --pre-hook "$process_path stop" --post-hook $procCmdLine -n --apache-server-root $server_root --apache-vhost-root $config_root
returnCode=$?
echo "The command exit status : ${returnCode}"
exit $returnCode

Example 2. Win-ACME (Windows)

set SERVERURL=%1
set SANS=%2
set EMAIL=%3
set KEYALGO=%4
set EABKEY=%5
set EABHMAC=%6
set VALIDATIONMODE=--validation selfhosting
"wacs.exe" --baseuri %SERVERURL% --eab-key-identifier=%EABKEY% --eab-key=%EABHMAC% --target manual --host %SANS% --emailaddress %EMAIL% --force --accepttos --notaskscheduler %VALIDATIONMODE% --csr %KEYALGO% --store centralssl --centralsslstore  ./certs
set returnCode=%errorlevel%
EXIT /B %returnCode%

Variable definitions at the top of these shell scripts read in the required ACME arguments:

These must match up with the ACME arguments you configure for the custom application in DigiCert®.
During an automation event, values for these arguments are supplied by the local DigiCert agent that calls the shell script.

Commands used in the shell script:

Must include all mandatory parameters.
Must not exceed 512 characters.
Must not include special directives like rm -rf or rmdir

The shell script filename:

Must end with .bat or .sh
Must not exceed 255 characters.

Add script details in Trust Lifecycle Manager

Store your custom automation shell script in the local agent's packages sub-directory and configure the details about it in Trust Lifecycle Manager:

From the Trust Lifecycle Manager main menu, select Integrations > Agents.
From the More actions dropdown at top, select Add script.
Fill out the Add script form:
1. Name: Enter a user-friendly name to use when referencing the script.
2. Operating system: Select the applicable operating system (Linux or Windows).
3. Script type: Select Custom automation.
4. Script filename: Enter the script's filename in or path relative to the local agent's packages sub-directory. The filename must start with ./ (Linux) or .\ (Windows) and cannot have any spaces in it. For example:
  - Linux: If your script is named "myscript.sh" and is stored directly in the agent's packages sub-directory, enter ./myscript.sh here. If you stored the script within an additional sub-directory called "custom-apps" in the packages sub-directory, enter ./custom-apps/myscript.sh instead.
  - Windows: If your script is named "myscript.bat" and is stored directly in the agent's packages folder, enter .\myscript.bat here. If you stored the script within an additional sub-folder called "custom-apps" in the packages folder, enter .\custom-apps\myscript.bat instead.
  Warning
  Make sure there are no spaces in the filename for either Linux or Windows. The script will fail if the path or filename has spaces in it.
5. Command-line arguments: Enter a space-separated list of general ACME parameters to use with your custom automation script.
  For example:
  {acmeDirectoryUrl} {hosts} {email} {key} {extActKid} {extActHmac}
  Note that:
  - Each argument must be entered exactly as shown here.
  - The order of the arguments must match up with how they are used in your shell script.
  - When you submit a certificate automation request from Trust Lifecycle Manager, it supplies the required values for these parameters based on the certificate profile and request details.
  Explanation of ACME parameters used by DigiCert®:
  - {acmeDirectoryUrl}: The ACME directory URL.
  - {hosts}: Domain name(s) for the certificate.
  - {email}: Add an email address to the certificate.
  - {key}: Key algorithm (RSA or ECC).
  - {extActKid}: External Account Binding (EAB) key identifier.
  - {extActHmac}: HMAC key for EAB.
6. Description (optional): Enter an optional description for the script to help identify it when working with DigiCert agents and agent-based automations in Trust Lifecycle Manager.
Select Add to save the custom automation script details in Trust Lifecycle Manager.

Assign script to the applicable agent IP/port targets

To complete the custom automation configuration, assign the script to any DigiCert agents that will coordinate certificate lifecycle automation events for the custom application:

From the Trust Lifecycle Manager main menu, select Integrations > Agents.
Locate the local DigiCert agents on the systems where the custom application is running. Select each agent by name to view the details for it.
Select the pencil (edit) icon on the right of the agent details page to update the agent configuration.
In the IP/port targets section for the agent, locate any IP/port targets where the custom application is running and configure them as follows:
- Application: Select Custom.
- Custom automation script: Select the custom automation script by the name assigned to it in Trust Lifecycle Manager.
Select the Update button at bottom to save your changes.

What's next

After enabling managed automation for your custom application, you can schedule certificate lifeycle automation events for it as you would any other application in Trust Lifecycle Manager.

In this section: