Configuring Script-Based Certificate Store Jobs

Documentation Suite v10.3

The Keyfactor Universal Orchestrator The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with Windows servers (a.k.a. IIS certificate stores) and FTP capable devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can run custom jobs to provide certificate management capabilities on a variety of platforms and devices (e.g. F5 devices, NetScaler devices, Amazon Web Services (AWS) resources) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux. supports the option to implement custom-built certificate store jobs using one or more scripts (PowerShell or Bash) rather than a full extension (see Installing Custom-Built Extensions). To implement custom-built certificate store jobs in this way, you need to create your scripts that will execute the certificate store actions (e.g. inventory, add certificates, remove certificates) and a manifest.json file to reference the jobs and install them on the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores.. Optionally, each certificate store action script can call a prescript and/or a postscript to perform actions before or after the main action.

Note: The scripting method of running custom-built certificate store jobs cannot be used to run other types of custom jobs. These are supported only with the use of a custom extension (see Installing Custom-Built Extensions). However, both certificate store jobs and custom jobs support the use of prescripts and postscripts (see Orchestrator Job Overview).

To configure a set of custom-built certificate store scripts:

On the Universal Orchestrator server, locate the scripts directory within the install directory. By default, this is:

Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\Scripts

Linux: /opt/keyfactor/orchestrator/Scripts
Under the scripts directory, create a new directory with an appropriate name for your custom-built certificate store job set (e.g. MyStore). This name matches the name of the job referenced in the manifest.json file.
Place the scripts created for your custom-built certificate store job set in the new directory. Supported script file names are:
- Add (e.g. Add.ps1 or Add.sh)
  A management job to add a certificate to the certificate store.
- Create (e.g. Create.ps1 or Create.sh)
  A management job to create the certificate store if it does not already exist.
- Discovery (e.g. Discovery.ps1 or Discovery.sh)
  A discovery job.
- Inventory (e.g. Inventory.ps1 or Inventory.sh)
  An inventory job.
- Reenrollment (e.g. Reenrollment.ps1 or Reenrollment.sh)
  A reenrollment job.
- Remove (e.g. Remove.ps1 or Remove.sh)
  A management job to remove a certificate from the certificate store.
In order to use a Bash script with orchestrators installed on Linux, you must first register the Bash script driver in the appsettings.json file. This file is found in the configuration directory. Edit the file and add the following below the existing AppSettings configuration section in the file (before the final closing bracket):
```
"extensions": {
   "Keyfactor.Orchestrators.ScriptDrivers.IScriptDriver": {
      "RegisteredScriptDriver": {
         "assemblypath": "Keyfactor.Orchestrators.BashDriver.dll",
         "TypeFullName": "Keyfactor.Orchestrators.ScriptDrivers.BashDriver"
      }
   }
}
```
On the Universal Orchestrator server, locate the JobExtensionDrivers directory within the extensions directory under the install directory. By default, this is:

Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions\JobExtensionDrivers

Linux: /opt/keyfactor/orchestrator/extensions/JobExtensionDrivers
In the JobExtensionDrivers directory, create a file called manifest.json or open the existing one. There should be only one manifest.json file no matter how many script directories you create.
Using a text editor, edit the manifest.json file and configure it appropriately for your custom-built certificate store job set. Some things to keep in mind are:
- The opening and closing lines of the file must match those shown in red here:
```
{
   "extensions": {
      "Keyfactor.Orchestrators.Extensions.IOrchestratorJobExtension": {
         "CertStores.MyStore.Inventory": {
            "assemblypath": "Keyfactor.Orchestrators.JobExtensionDrivers.dll",
            "TypeFullName": "Keyfactor.Orchestrators.JobExtensionDrivers.InventoryJobExtensionDriver"
         }
      }
   }
}
```
- Each customized section of the file starts with a certificate store reference (e.g. CertStores.MyStore.Inventory). Certificate stores jobs (beginning CertStores) correspond to certificate store types created with the Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. POST /CertifiateStoreType method (see POST Certificate Store Types in the Keyfactor Web APIs Reference Guide) or in the Keyfactor Command Management Portal (see Adding or Editing a Certificate Store Type in the Keyfactor Command Reference Guide). For example, a custom certificate store type with a Capability of MyStore configured to do inventory, management and discovery, would have three separate sections in the file as CertStores.MyStore.Inventory, CertStores.MyStore.Management, and CertStores.MyStore.Discovery. The capability reference (e.g. MyStore) must also match the name you give to the directory where you place your scripts. An inventory section is required.
- The assemblypath referenced in each section points to the DLL in the extensions directory of the Job Extensions Driver extension. This built-in extension is used to run custom-built certificate store jobs as scripts. This value will be the same for all entries in the file.
- The TypeFullName referenced in each section corresponds to the name of the type that resides inside of the DLL listed for the assembly path—the Job Extensions Driver extension in this case. This value will be the same for all entries in the file.
- Each section may optionally have a PreScript reference, which points to an additional script file on the orchestrator machine that will run before the main job for the section executes.
  Tip: If either your PreScript or PostScript fails, this will cause the entire job to fail. You can use this to your advantage if you'd like to fail the job under certain conditions by doing a Write-Error on Windows or exit <error code> on Linux.
- Each section may optionally have a PostScript reference, which points to an additional script file on the orchestrator machine that will run after the main job for the section executes.
- Custom-built certificate store jobs support up to four job types—Inventory, Management, Discovery, and Reenrollment. Each one of these job types should have a separate section in the file.
Restart the Universal Orchestrator service (see Start the Universal Orchestrator Service).
In the Keyfactor Command Management Portal, re-approve the orchestrator. The orchestrator will update to a status of new (if it had been approved previously) upon receiving updated capabilities. See Orchestrator Management in the Keyfactor Command Reference Guide for information on approving orchestrators.

Contact your Keyfactor representative for more information about custom solutions or for assistance creating custom scripts.

Configuring Script-Based Certificate Store Jobs

Products

Solutions

Resources

Company