Deploy certificates for custom applications

DigiCert® Trust Lifecycle Manager provides the ability to extend certificate management to custom applications, by using the Admin web request function with custom post-delivery scripts. This automation framework uses DigiCert agents to distribute certificates to your environment. You manage deployments from the centralized Trust Lifecycle Manager web console.

Avis

DigiCert provides the following GitHub repository with tools and resources for integrating different platforms using this custom agent-based automation framework:

https://github.com/digicert/product-solutions

Before you begin

The Automation feature must be enabled for your Trust Lifecycle Manager account. For help verifying or enabling this feature, contact your DigiCert account representative.
You need at least one active DigiCert agent installed on your network. The required agent OS depends on the type of script you will use to manage certificates for your system or application:
- Windows agent: To use a bat, cmd, or PowerShell script.
- Linux agent: To use a shell script (for example, bash).
To deploy certificates to a remote system, the agent needs outbound network access to the target system via the mechanism your script will use to install certificates (for example, API or SSH).
You need one or more certificate profiles for the Admin web request enrollment method.
- When creating certificate profiles for automated delivery, look for base templates that list Admin web request in the Use cases column.
- For CertCentral certificate profiles, only OV/EV certificate products can be requested for delivery. Make sure to select an OV or EV product in the Certificate type dropdown when using the Admin web request enrollment method.

Step 1: Create the post-delivery script

Your custom post-delivery script defines the actions to take after a certificate is delivered to the local DigiCert agent. This might include:

Installing the certificate for a local web or server application.
Connecting to a remote system to install the certificate through API, SSH, or similar means.

Use one of the following languages to create your custom script, depending on the OS of the local agent where you'll deploy it:

Windows: bat, cmd, or PowerShell script
Linux: shell script (any)
For script templates and detailed instructions, see Admin web request templates

Follow these tips to ensure a successful implementation:

The enrollment request sent from Trust Lifecycle Manager can include up to 15 optional parameter values, which are passed to the script as command-line arguments.
The local DigiCert agent records data about the delivered certificate in the DC1_POST_SCRIPT_DATA environment variable in Base64-encoded JSON format.
- Target and decode this variable in your script to get the values of any command arguments and the parameters needed to pick up the certificate and deploy it to the target application.
- For details about the JSON fields stored in the DC1_POST_SCRIPT_DATA variable, see Script execution data.
Test your script thoroughly before adding it to Trust Lifecycle Manager to ensure it performs the required certificate deployment actions for your application.

Step 2: Add the script in Trust Lifecycle Manager

Once you've created and tested the custom post-delivery script, follow these steps to add the script to Trust Lifecycle Manager:

In the Trust Lifecycle Manager menu, go to Discovery & automation tools > Scripts > DigiCert agents.
Open the Add script for dropdown on the top-right, and select DigiCert agents.
Complete the Add new script sidebar:
- Name: Enter a user-friendly name to identify the script.
- Operating system: Select the applicable operating system (Linux or Windows).
- Script type: Select Admin request post-delivery.
- Upload script: Drag and drop or browse to select the script to upload. Once uploaded, the name of the script appears below the widget.
- Description: (Optional) Enter an optional description for the script.
Select Add and verify script to verify the script in Trust Lifecycle Manager. Once verified, the script is available for assignment.

When you add a script, Trust Lifecycle Manager scans it for malicious content. If the script passes verification, it appears on the Discovery & automation tools > Scripts > DigiCert agents page and shows Active in the Status column. The script is now available for assignment.

Step 3: Request a new certificate for the application

To request and deploy a new certificate for your application from Trust Lifecycle Manager:

On the Inventory page, select the Admin web request button at top.
On the Certificate setup screen, configure the basic certificate options:
1. Profile: Select a certificate profile to enroll from. Only profiles with the Admin web request enrollment method are included in this dropdown menu. Use the Show details link to verify the properties for the selected certificate profile.
2. Certificate information:
  Common Name: Enter a common name (CN) for the new certificate.
  Other hostnames (SANs): Enter subject alternative names to include in the new certificate, one at a time. To instead import the list of SANs from a CSV file, select the Import CSV button. This field is optional and only appears if supported by the selected certificate profile. Depending on the profile configuration, you can enter DNS names, IP addresses, or both.
3. Lifecycle & fulfillment controls:
  Issue duplicate certificate if available: For CertCentral orders, issue a duplicate certificate if the selected profile supports it and the requested common name and SANs match an existing certificate.
  Enable auto-renew schedule: Enable this option to automatically renew the certificate before expiration and deliver the new certificate to the same delivery locations. Select options for when to submit the renewal request (number of days before expiration). Selections you make here override any auto-renewal options in the certificate profile. During an auto-renewal event, the new certificate gets delivered to the same locations as the original one.
4. Certificate-level settings:
  Certificate owners (optional): Select any certificate owners for the certificate. If the selected certificate profile allows it, you can add new owners as part of the request.
  Tags (optional): Apply tags to the issued certificate to help monitor and manage it in Trust Lifecycle Manager.
  Custom attributes (optional): Select any custom attributes for the certificate. This option only appears if the selected certificate profile includes the configured attributes.
5. Additional order options: Enter order handling information, not to be included in the certificate itself. This section is optional and only appears if supported by the selected certificate profile.

On the Delivery integrations screen, configure the delivery targets:

Select the Add button.
In the sidebar that opens, enable Agents and select Apply.
Select Agents on the left to configure the delivery options for agents.
In the DigiCert agents dropdown on the right, select one or more agents to deliver to.

For each agent you selected, configure options for each individual delivery location:

Format: Select one of the certificate delivery formats in the following table and provide the requested delivery options for it.

Avis

The reference scripts in the Integrations GitHub repository deploy certificates as CRT or PKCS#12 (PFX) files. To use these scripts, select either .crt or .pkcs12 as the delivery format, or modify the script to support a different format.

Format	Description	Delivery options
`.crt`	Deliver the end-entity certificate as a CRT file.	Target path: Enter the full pathname for the directory to deliver the certificate to.
`.jks (update existing)`	Deliver the certificate and any associated materials to an existing Java KeyStore (JKS).	Target path: Enter the full path for the JKS keystore file to add the certificate to. Key store password: Enter the password for the JSK keystore. Trust store password: Enter the password for the trust store for adding any CA certificates.
`.jks (new)`	Create a new Java KeyStore (JKS) for delivering the certificate.	Target path: Enter the full path where the new JKS keystore file should be created. Key store password: Enter a password for the new JSK keystore. Trust store password: Enter the password for the trust store for adding any CA certificates.
`.pem`	Deliver the certificate and any associated materials in PEM format.	Target path: Enter the full pathname for the directory to deliver the certificate to. Password for certificate files: Enter a password for encrypting the private key.
`.pkcs12`	Deliver the certificate and any associated materials in PKCS#12 (PFX) format.	Target path: Enter the full pathname for the directory to deliver the certificate to. Password for certificate files: Enter a password for protecting the PFX file.
`.p7b`	Deliver the certificate and certificate chain as a PKCS#7 (P7B) file.	Target path: Enter the full pathname for the directory to deliver the certificate to.
`CAPI`	Deliver the certificate and any associated materials to the Windows Certificate Store (CAPI). Note: Available for Windows agents only.	Store location: Select `LocalMachine` (all users) or `CurrentUser` (current user only). Certificate store: Select the name of the store to add the certificate to.
`GSK`	Deliver the certificate and any associated materials to an IBM Global Security Kit (GSK) keystore. Prerequisites: For Windows agents, the GSK executable bin directory must be included in the system `PATH` environment variable on the host system. For Linux agents, specify the full file path to the GSK executable bin directory in the agent configuration, under Admin request delivery location.	Keystore type: Select `KDB` or `PKCS12`. Keystore file path: Enter the full path for the keystore file to add the certificate to. The keystore file will be created if it doesn't already exist. Password for certificate files: Enter the password for the GSK keystore. Certificate label: Enter a unique label for the certificate in the GSK keystore. Delete and replace existing: Select this option to enable deleting and replacing any existing certificate with the same label as this one. Otherwise, the new certificate will not be delivered if there's an existing certificate with the same label.

Enable the Run-post delivery scripts option and configure the following:
- Script: Select your post-delivery script for deploying certificates to the custom application.
- Parameters: Enter values for up to 15 command-line arguments to pass to your custom script.
(Optional) To configure additional delivery locations on the same agent, select Add destination.

On the Review & Submit screen, review all the options you selected and submit the request:
1. Review the options you selected in the Certificate Details and Delivery Integrations sections. To make changes on either screen, select Edit on the right.
2. When you're ready to proceed, select the link at the bottom to read the Certificate Services Agreement, then check the box to acknowledge/agree to it.
3. Select Submit request to finish and submit the certificate enrollment/delivery request.

When you submit the request, the certificate is issued and delivered to the agents you selected. Each agent records the delivery parameters in the DC1_POST_SCRIPT_DATA environment variable, then invokes your post-delivery script to deploy the certificate to the target application.

You can track the certificate deployment from the Inventory page in Trust Lifecycle Manager.

Verify or troubleshoot script execution

Use either of the following methods to verify execution of an agent post-delivery script and see any error details for it:

In the Trust Lifecycle Manager web console, go to Inventory > Endpoints. Find the certificate in the table, and select the information icon in the rightmost column to open the automation progress tracker. In the Post script step, select the View Delivery Details button to see logs and error messages about script execution. To learn more, see Track progress of certificate automation requests.
On the local DigiCert agent host, check the Trust Lifecycle Manager plugin manager (TPM) logs for delivery and script execution details. To learn more, see Troubleshoot agents.

Ongoing certificate management

The deployed certificate is added to your Trust Lifecycle Manager inventory where you can manage it. For details, see Manage an existing certificate deployment
If you enabled auto-renewal for the certificate, Trust Lifecycle Manager automatically delivers a new certificate to the same location as the original certificate when it approaches expiration.
When you manage a delivered certificate or when it auto-renews, Trust Lifecycle Manager delivers the new certificate to the same agents using the same certificate profile. The agent uses the same post-delivery script, but downloads a fresh copy of the script from Trust Lifecycle Manager each time:
- To have the agent use a new version of the script during subsequent automation runs, update the script in Trust Lifecycle Manager. See Manage scripts.
- The agent reuses the values of any script command arguments supplied in the original enrollment request. To update the argument values, add the new arguments into the script itself or cancel the scheduled automation and submit a new delivery request.

Dans cette section: