Upgrading the Universal Orchestrator

There are two possible paths for upgrading from an earlier implementation of the Keyfactor Universal OrchestratorClosed 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. to a newer implementation:

If you have an existing instance of the Keyfactor Windows Orchestrator and wish to migrate to the Keyfactor Universal Orchestrator, you may either install the two orchestrators side-by-side and then uninstall the Keyfactor Windows Orchestrator or uninstall the Keyfactor Windows Orchestrator and then install the Keyfactor Universal Orchestrator.

Important:  Before following any of these upgrade paths, be sure to save off a copy of any custom extensions for the Keyfactor Universal Orchestrator (found in C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions by default) or plugins for the Keyfactor Windows Orchestrator (found in C:\Program Files\Keyfactor\Keyfactor Windows Orchestrator\plugins by default).

Keyfactor’s suggested upgrade process is:

  1. Review your installed orchestrator and gather this information:

    • Is this a Windows Orchestrator or a Universal Orchestrator?

      There are a number of ways to tell the difference. For example, the default install directory for the Universal Orchestrator is Keyfactor Orchestrator which the default install directory for the Windows Orchestrator is Keyfactor Windows Orchestrator. The Universal Orchestrator has several subdirectories, including an extensions directory. The Keyfactor Windows Orchestrator has only one subdirectory—plugins—by default.

    • What user account is being used to run the orchestrator service?

      To check this, you can open the Windows Services tool (services.msc), look for the Keyfactor Orchestrator Service, and check the account that’s configured as the Log On As.

    • If this installation is on Windows, is the user account being used to run the orchestrator service a group managed service account (gMSA)?

    • What type of authentication is being used to make the connection to Keyfactor Command?

      To check this, you can open the appsettings.json configuration file, which is found in the following location by default:

      Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\appsettings.json
      Linux: /opt/keyfactor/orchestrator/configuration/appsettings.json

      If you’re using client certificate authentication, the CertPath and AuthCertThumbprint fields will be populated. If you’re using token authentication, the BearerTokenUrl and ClientId fields will be populated. If none of the aforementioned fields are populated, you’re using Basic authentication.

    • What user account, client ID, or other authentication information is being used to make the connection to Keyfactor Command?

      Check in Keyfactor Command for the Identity that the orchestrator indicates on the Orchestrator Management page.

    • What secret information (user password, client secret, etc.) is used to make the connection to Keyfactor Command?

      This information cannot be retrieved from your existing installation. It is stored in an encrypted state.

    • What plugins (Windows Orchestrator) or extensions (Universal Orchestrator) are you using?

      The plugins for the Keyfactor Windows Orchestrator are found in C:\Program Files\Keyfactor\Keyfactor Windows Orchestrator\plugins by default. The extensions for the Keyfactor Universal Orchestrator are found in C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions by default.

  2. If you're using plugins or extensions:

    1. Before beginning the upgrade, save off a copy of any existing plugins or extensions in use.

    2. If you’re using plugins or extensions from the Keyfactor Git Hub, check for the latest version:

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

      Plugins for the Keyfactor Windows Orchestrator are not compatible with the Keyfactor Universal Orchestrator, so check for extensions that replace your plugins.

    3. Review the documentation of each extension you will be using to determine if there are any changes needed to the certificate store type definition in Keyfactor Command. Only the following fields in a certificate store type that’s in use may be edited:

      • Name

      • Short Name

      • Supported Job Types

      • Entry Parameters

      If changes to any other fields of the certificate store type are needed, you will need to create a new certificate store type.

    4. Create new certificate store types or edit existing certificate store types as needed (see the previous step). If you’re creating a new certificate store type to replace an existing one, it cannot have the same Short Name as an existing certificate store type. This means that you will most likely be using a non-standard Short Name for your extension (e.g. CitrixAdc2) and will need to modify the extension configuration to point it to the correct certificate store type. To do this, in the directory for your extension (the version that you will later copy into the upgraded orchestrator’s directory), locate the manifest.json file and open it for editing. Change the existing capability to map to your new certificate store type(s). For example, CitrixAdc becomes CitrixAdc2:

      Copy 
      {
         "extensions": {
            "Keyfactor.Orchestrators.Extensions.IOrchestratorJobExtension": {
               "CertStores.CitrixAdc2.Inventory": {
                  "assemblypath": "Keyfactor.Extensions.Orchestrator.CitricAdc.dll",
                  "TypeFullName": "Keyfactor.Extensions.Orchestrator.CitricAdc.Inventory"
               },
               "CertStores.CitrixAdc2.Management": {
                  "assemblypath": "Keyfactor.Extensions.Orchestrator.CitricAdc.dll",
                  "TypeFullName": "Keyfactor.Extensions.Orchestrator.CitricAdc.Management"
               }
            }
         }
      }

  3. Install the new Universal Orchestrator, either uninstalling the previous version or installing over the previous version using the -force option, following the standard installation steps (see Install the Universal Orchestrator on Windows, Install the Universal Orchestrator on a Linux Server, or Install the Universal Orchestrator in a Linux Container) and referencing the information you gathered in step 1. If you’re installing in a container, you’ll need to stage your selected extensions as part of the install.

  4. If you’re using extensions and didn’t install in a container, copy your extensions into the extensions directory of the new orchestrator (see Installing Custom-Built Extensions). Restart the orchestrator service to pick up the extension changes.

  5. In the Keyfactor Command Management Portal, review the orchestrator, confirm that the capabilities are as expected, and approve the orchestrator.

  6. If you’re using extensions and added a new certificate store type, you will need to recreate your certificate store. The certificate store type associated with a certificate store cannot be edited. Review your current certificate stores and recreate them with the new certificate store type, and then delete the versions with the old certificate store type.

  7. Confirm that your certificate stores and/or SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scanning are functioning as expected.