DigiCert® Trust Lifecycle Manager supports the following script types to customize agent-based certificate lifecycle management on your servers. Select the links for more details about each script type.
Script type | Description |
---|---|
Manage certificates for custom server applications. | |
Dynamically learn the SNI domains used by DigiCert agents to discover and manage certificates. | |
Do extra work before installing a certificate for a web server application during an automation event. | |
Do extra work after installing a certificate for a web server application during an automation event. | |
Do extra work after delivering a certificate to a server system using the admin web request enrollment method. |
Importante
Use one of the following languages for your custom agent scripts, based on the host operating system:
Windows: bat, cmd, or PowerShell script
Linux: shell script (any)
If you use a different language/format to do work, use one of the above scripting languages as a wrapper to ensure compatibility.
Use custom automation scripts to manage certificates for custom server applications through DigiCert agents.
This type of script allows you to use your own ACME client like Certbot on your server to manage certificate lifecycles for applications not natively supported by Trust Lifecycle Manager.
You configure the custom automation script to invoke the third-party ACME client with the options needed to request and install certificates for your application.
To learn more, see Configurar um aplicativo personalizado para automação gerenciada.
Trust Lifecycle Manager requires administrators to supply a list of active domains in order to discover and automate certificates on websites using Server Name Indication (SNI). You can use SNI information scripts to dynamically learn the SNI domains on your servers so you don't need to configure them manually.
For example, you might read the SNI domains directly from your web server configuration to ensure that your DigiCert agents always have the latest information.
To simplify management, Trust Lifecycle Manager allows you to assign the scripts across multiple agents in bulk.
Set up your SNI script to output the SNI information as JSON in the following format.
[
{
"IP": "10.1.2.3",
"Port": "8443",
"Domain": "www.example.com"
},
{
"IP": "10.1.2.3",
"Port": "8443",
"Domain": "app2.example.com"
}
]
The following example SNI information script uses the Microsoft PowerShell scripting language to read the latest SNI information from the local IIS web server. It outputs the information as JSON to use to dynamically configure the local DigiCert agent.
$bindingInfo = get-website | select -ExpandProperty Bindings | Select -ExpandProperty Collection | where sslFlags -eq 1 | select bindingInformation
$res = @{}
foreach($ele in $bindingInfo) {
$list = $ele.bindingInformation.split(":")
$res[$list[2]] = @{IP=$list[0]; Port=$list[1]; Domain=$list[2]}
}
$thumbs = Get-ChildItem IIS:SSLBindings | Foreach-Object {
[PSCustomObject]@{
Host = $_.Host
Thumbprint = $_.Thumbprint
}
}
echo($res.values | ConvertTo-Json)
Use pre- or post-installation scripts to do extra work before an automation event (pre-installation) or after the local DigiCert agent installs the certificate in an automation event (post-installation).
This type of script allows you to do any type of work needed to facilitate PKI operations on your servers, such as readiness testing, preparation, or clean up. You can use different pre- or post-installation scripts per web server application.
To simplify management, Trust Lifecycle Manager allows you to assign the scripts across multiple agents in bulk.
Return 0
from a pre-installation script for success, or non-zero for failure. Avoid using return codes 1
, 127
, or 4294770688
as they are pre-defined by the agent for other purposes.
With pre-installation scripts, the DigiCert agent will cancel the automation event if the script does not return a success code of 0
. This helps you control when a certificate is automated based on an external input.
Use this script type to perform extra work after delivering a certificate from Trust Lifecycle Manager to an external server system using the admin web request enrollment method.
When you assign the post-delivery script to an agent-based certificate automation event, you can enter up to five parameters to pass to the target host to control how the script gets executed there.
During a certificate delivery event, the local DigiCert agent adds script-related data to the DC1_POST_SCRIPT_DATA
environment variable in Base64-encoded JSON format. Target and decode this variable in your post-delivery scripts to get the list of parameters passed from Trust Lifecycle Manager and other relevant details to help process the delivered certificate, as in the following examples:
Example of decoded
DC1_POST_SCRIPT_DATA
environment variable value after delivering a PKCS#12 certificate (.pfx
file extension) on a Windows system:{"args":["abc", "def"],"certfolder":"C:\Program Files\DigiCert\TLM Agent\.secrets","files":["my-cert-1.pfx"], "password":"P@ssw0rd"}
Example of decoded
DC1_POST_SCRIPT_DATA
environment variable value after delivering an X.509 certificate (.crt
file extension) on a Linux system:{"args":["abc","def","ghi"],"certfolder":"/opt/tlm_agent/.secrets","files":["my-cert-1.crt","my-cert-1.key"]}
JSON fields in the output depend on the type of certificate delivered and may include:
JSON field | Description | Certificate types |
---|---|---|
| List of up to five extra parameters passed to the script from Trust Lifecycle Manager. | All |
| Directory path where the certificate was delivered. | All |
| Names of the certificate files delivered to the above directory. | All |
| The password used to encrypt the certificate file. | PKCS#12 (PFX), PEM, P7B |
| Password for the keystore where the certificate was delivered. | JKS |
| Password for the truststore where the certificate was delivered. | JKS |
The following example post-delivery script uses the Microsoft PowerShell scripting language to import a delivered PKCS#12 (PFX) certificate to the LocalMachine\My certificate store on a Windows system. The script decodes and parses the JSON in the DC1_POST_SCRIPT_DATA
environment variable to determine the certificate filename, password, and directory where it was delivered by the local DigiCert agent.
# Function to decode base64 encoded string
function Decode-Base64 {
param (
[string]$base64String
)
$bytes = [System.Convert]::FromBase64String($base64String)
$decodedString = [System.Text.Encoding]::UTF8.GetString($bytes)
return $decodedString
}
# Base64 encoded JSON input
$base64Json = [System.Environment]::GetEnvironmentVariable("DC1_POST_SCRIPT_DATA")
# Decode the base64 encoded JSON
$jsonString = Decode-Base64 -base64String $base64Json
# Convert JSON string to PowerShell object
$jsonObject = $jsonString | ConvertFrom-Json
Write-Host "Arguments : "$jsonObject.args
# Extract values from JSON object
$certFolder = $jsonObject.certfolder
$pfxFile = Join-Path -Path $certFolder -ChildPath $jsonObject.files[0]
$password = $jsonObject.password
# Validate inputs
if (-not (Test-Path -Path $pfxFile)) {
Write-Error "ERROR: The PFX file does not exist."
exit 1
}
# Import the PFX file into the LocalMachine\My store
try {
$cert = Import-PfxCertificate -FilePath $pfxFile -CertStoreLocation Cert:\LocalMachine\My -Password (ConvertTo-SecureString -String $password -Force -AsPlainText)
if ($null -eq $cert) {
throw "Failed to import the certificate."
}
Write-Output "Certificate imported successfully."
} catch {
Write-Error "ERROR: Failed to import the certificate. $_"
exit 1
}
The following example post-delivery script uses the Bash shell scripting language to import a delivered X.509 (CRT) certificate to the /etc/pki/ca-trust/source/anchors trusted CA directory on a Red Hat-based Linux system that has the ca-certificates
package installed. The script decodes and parses the JSON in the DC1_POST_SCRIPT_DATA
environment variable to determine the certificate filename and directory where it was delivered by the local DigiCert agent.
#!/bin/bash
# Step 1: Read the Base64-encoded JSON string from the environment variable
CERT_INFO=${DC1_POST_SCRIPT_DATA}
if [[ -z "$CERT_INFO" ]]; then
echo "Error: Environment variable 'DC1_POST_SCRIPT_DATA' is not set or is empty."
exit 1
fi
# Step 2: Decode the Base64 string into JSON
JSON_STRING=$(echo "$CERT_INFO" | base64 -d)
# Step 3: Parse JSON manually to extract 'certfolder' and '.crt' file
CERT_FOLDER=$(echo "$JSON_STRING" | grep -oP '"certfolder":"\K[^"]+')
CRT_FILE=$(echo "$JSON_STRING" | grep -oP '"files":\["\K[^"]+\.crt')
if [[ -z "$CERT_FOLDER" || -z "$CRT_FILE" ]]; then
echo "Error: Invalid JSON data. Could not find 'certfolder' or '.crt' file."
exit 1
fi
# Step 4: Construct full path to the certificate file
CRT_FILE_PATH="${CERT_FOLDER}/${CRT_FILE}"
if [[ ! -f "$CRT_FILE_PATH" ]]; then
echo "Error: Certificate file not found at path '$CRT_FILE_PATH'."
exit 1
fi
# Step 5: Copy the certificate to the system's trusted CA directory
TRUSTED_CA_DIR="/etc/pki/ca-trust/source/anchors"
DEST_CRT_FILE="${TRUSTED_CA_DIR}/$(basename "$CRT_FILE")"
echo "Copying certificate to trusted CA directory..."
sudo cp "$CRT_FILE_PATH" "$DEST_CRT_FILE"
# Step 6: Update the system's trusted certificates
echo "Updating trusted certificates..."
sudo update-ca-trust extract
if [[ $? -eq 0 ]]; then
echo "Certificate successfully added to the system's trusted certificates."
else
echo "Error: Failed to update the trusted certificates."
exit 1
fi