Documentation Suite v11.3

Installing Custom-Built Extensions

Keyfactor offers many custom-built extensions for 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. on GitHub:

https://keyfactor.github.io/integrations-catalog/content/orchestrator

Some packages that may be of special interest to long-term users of Keyfactor Command are:

Tip: Unlike the Keyfactor Java Agent

The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed., which must be installed directly on each machine holding Java keystores to be managed, the Keyfactor Universal Orchestrator

Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. with the Remote File extension is a centralized orchestrator, which is installed on just a single machine (or handful of machines) and then reaches out via remote management to each machine holding Java Keystores to be managed. For Java keystores on Windows servers, it uses PowerShell remoting and WinRM, typically over HTTPS, for this (see Configure Windows Targets for Remote Management). For Java keystores on Linux servers, it uses either SCP or SFTP (configurable on a per-orchestrator basis and can be configured to try both). Large-scale deployment of Java keystore management (or any of the other formats supported by this extension) involves enabling PowerShell remoting and WinRM with HTTPS on Windows targets (and a local login user if the servers aren’t domain joined) or enabling SCP or SFTP and creating a login user for the orchestrator on Linux targets.

Note: For information about installing PAM extensions for the Universal Orchestrator, see Installing Custom PAM Provider Extensions.

To find a package on GitHub:

Visit one of the links above to find your desired package, and click either Github Repository or View source on GitHub to go to the package page on GitHub.

Figure 574: View Packages as Part of a List

Figure 575: View Packages on Individual Pages
On the GitHub page, on the right-hand side, click the link for the Latest version.

Figure 576: Find the Latest Version of the Package
On the GitHub version page in the Assets section, click the package name to download the zip file.

Figure 577: Download the Package Zip File
On the main extension GitHub page, review the documentation for the specific extension. Here you will find supported platforms, prerequisites, and extension-specific installation and configuration instructions. The below instructions only cover where to place the extension files on the orchestrator and building custom manifest.json files (changes to which aren’t needed for extensions from GitHub unless you are customizing something), but not the details for creation of custom certificate store types for the extension or any other customization specific to a given extension.

Custom-built extensions can also be generated by end users using the Universal Orchestrator 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:

In the Keyfactor Command Management Portal or using 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., add a certificate store type or custom job type for your custom-built extension, if applicable. See Adding or Editing a Certificate Store Type or POST Custom Job Types
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 if needed and configure it appropriately for your application.

Tip: This step is generally not needed for extensions downloaded from GitHub unless you have opted to make customizations or not use the suggested short name when creating the certificate store type.

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": {
         "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 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) or in the Keyfactor Command Management Portal (see Adding or Editing a Certificate Store Type). 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):
    Copy
    "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.
  
  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 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 for information on approving orchestrators.

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.

Version v11.3

On this page: