Installing Custom-Built Extensions

Documentation Suite v10.3

Custom-built extensions for 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. are generated using the Universal Orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. NuGet package. Custom-built extensions for certificate store jobs and custom jobs are both installed in the same way.

Once you have your custom-built extension ready, install it as follows:

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

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

Linux: /opt/keyfactor/orchestrator/extensions
Under the extensions directory, create a new directory with an appropriate name for your custom-built extension (e.g. MyExtension). This name is for reference only and does not need to match any names used elsewhere.
Place the DLL(s) created for your custom-built extension along with any other supporting files needed for the extension in the new directory.
In the directory for your custom-built extension, create a file called manifest.json if one has not been provided with the extension. The manifest.json file must be placed in the same directory as the DLL(s) for your extension.
Using a text editor, edit the manifest.json file and configure it appropriately for your application. 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": {
         "Custom.MyJob": {
            "assemblypath": "Keyfactor.Orchestrators.MyJob.dll",
            "TypeFullName": "Keyfactor.Orchestrators.MyJob.MyJobExtension"
         }
      }
   }
}
```
- Each customized section of the file starts with either a custom job reference (e.g. Custom.MyJob) or a certificate store reference (e.g. CertStores.MyStore.Inventory).
  Custom jobs (beginning Custom) correspond to custom job 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 /JobTypes/Custom method. For example, a custom job type with a JobTypeName of MyJob would appear in the file as Custom.MyJob.
  Certificate store jobs (beginning CertStores) correspond to certificate store types created with the Keyfactor API 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 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. An inventory section is required.
- The assemblypath referenced in each section points to the DLL in the extensions directory that corresponds to that job function. A single manifest file may include many different capabilities if the extension performs more than one type of job (e.g. inventory and management of certificates), such as is shown in the below example.
- The TypeFullName referenced in each section corresponds to the name of the type that resides inside of the DLL listed for the assembly path. A single manifest file may include many different capabilities if the extension performs more than one type of job (e.g. inventory and management of certificates), such as is shown in the below example.
- Each section may optionally have a PreScript reference, which points to a script file on the orchestrator machine that will run before the main job for the section executes. Show scripting details.
  - For orchestrators installed on Windows, these will be PowerShell scripts. No special configuration is needed other than entry of a path to the PowerShell script in the PreScript field. The script may be placed anywhere on the orchestrator machine. The orchestrator will need read permissions to the script.
  - For orchestrators installed on Linux, these will be Bash scripts. In order to use a Bash script with the orchestrator, 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"
      }
   }
}
```
    After the Bash script driver is registered, you may enter a path to the Bash script in the orchestrator manifest.json file PreScript section. The script may be placed anywhere on the orchestrator machine. The orchestrator will need read permissions to the script.
  Tip: If your script 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.
  For more information about calling scripts from the orchestrator, contact your Keyfactor representative.
- Each section may optionally have a PostScript reference, which points to a script file on the orchestrator machine that will run after the main job for the section executes. See the notes for script use under PreScript.
- User-defined 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.
In the Keyfactor Command Management Portal or using the Keyfactor API, add a certificate store type or custom job type for your custom-built extension, if applicable. See Adding or Editing a Certificate Store Type in the Keyfactor Command Reference Guide or POST Custom Job Types in the Keyfactor Web APIs Reference Guide.

Contact your Keyfactor representative for more information about custom-built solutions or to obtain access to the NuGet packages required for development of Universal Orchestrator extensions.

Installing Custom-Built Extensions

Products

Solutions

Resources

Company