Documentation Suite v11.3

Configuring Script-Based Certificate Store Jobs

The Keyfactor Universal Orchestrator The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and 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 provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. 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):

Copy

"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 lines 1-3 and 8-10 here:
  Copy
```
1
2
3
4
5
6
7
8
9
10
{
   "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) or in the Keyfactor Command Management Portal (see Adding or Editing a Certificate Store Type). 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.
  Note: The prescript and postscript functionality of the Keyfactor Universal Orchestrator has been replaced by other functionality in Keyfactor Command such as that provided by Keyfactor Command workflows (see Workflow Definitions). As a result, prescript and postscript functionality has been deprecated and will be removed from a future release.
- 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 for information on approving orchestrators.

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

Version v11.3

On this page: