Skip to main content
Skip table of contents

Configuring the Universal Orchestrator

Introduction to the Universal Orchestrator

The Keyfactor Universal Orchestrator plays a crucial role in your CLM setup. It is tasked with scanning, discovering, investigating, and reporting back to Command the information that is found. Depending on your setup, it offers a range of capabilities, such as:

  • SSL discovery and monitoring: Use various third-party plugins to keep an eye on SSL certificates.

  • Log collection: Gather logs centrally for review within Command.

The Universal Orchestrator is designed to reside within the client network where it can interact effectively. It offers flexibility in deployment, with options available for Windows, Linux, or container environments.

Prerequisites

Before you start configuring, make sure you have completed the following.

  • Download the appropriate installer, tailored to your needs, from within the SaaS Portal and save it to the Orchestrator machine.

  • Acquire the necessary credentials for your installation, such as service account credentials (if applicable).

  • Acquire the required credentials for connecting to Command. Your client secret can be accessed from the SaaS Portal.

  • Ensure that the public IP of the server where the Orchestrator will be installed has been whitelisted in the SaaS Portal.

Beginning configuration

Start configuration by downloading the Universal Orchestrator and the SetupOrchestrator script from the Orchestrators tab in the SaaS Portal. This script is designed to help the installation of the Universal Orchestrator on different systems and connect back to your Command SaaS deployment.
There is a Windows PowerShell version and a Linux version.
The script is not required, should you want to install the Universal Orchestrator manually, but it can make the process easier by using preconfigured values that are specific to your Command SaaS deployment.

image-20240319-230045.png

Windows installation

Step 1

Provision a Windows host that is capable of running the Universal Orchestrator. Windows Server 2016-2022 is recommended.

Step 2

Place the SetupOrchestrator_{deploymentName}.ps1 script in a directory with the UniversalOrchestrator .zip file that you downloaded from the Command SaaS Portal.

It is required to run this script as an administrator. If you cannot elevate a PowerShell window to Administrator, please contact a System Administrator to provide these credentials.

In the following example, the script and .zip file were placed in a directory called “C:\UniversalOrchestrator”.

image-20240313-192511.png

Step 3

Run the script by right-clicking the script file, and then selecting Run with PowerShell or by opening a PowerShell window and executing the script.

image-20240313-192709.png

There are three options you can use when running the installation script.

  • Option 1 will install the Universal Orchestrator as a service with a user account and credentials that the script will automatically generate. This is the “easy button” version of this script. If you don’t want to create users and permissions, the script will create them all for you.

  • Option 2 will install the Universal Orchestrator as a service, but will prompt you for a domain username and password that has rights to the network and server. This is the recommended method.

  • Option 3 will install the Universal Orchestrator and attempt to run it in a PowerShell window without a service. Each time the server is restarted or the window is closed, the Universal Orchestrator will need to be started manually.

image-20240314-014513.png

Step 4

The first thing the installation script will do is try to connect to the Command SaaS deployment.

image-20240313-193219.png

If the connection fails, this is likely because it is required to allow any addresses into the Command SaaS deployment via the Self-Service Source IP feature of Command SaaS.

image-20240314-033156.png

If the process fails, add the outbound internet IP of the host you are using to your Command SaaS deployment.

One option to determine the outbound IP address of the host you are using is to type the following command in the PowerShell window.
Note: This method uses the third-party service ifconfig.me.

CODE
curl ifconfig.me

The response will show the IP address that your host will use to access the Command SaaS Deployment.

image-20240313-193832.png

Add this IP address to the Source IPs screen in the Command SaaS Portal for this deployment. Click Add, and then click Apply Now.

image-20240328-195258.png

Step 5

Once the change has processed, run the script again. The script will install .NET, if needed. If .NET already exists, the script will skip this step.

The remainder of the step is determined based on the installation option you selected.

If you selected Option 1

Selecting Option 1 will create the user for the service account automatically. Once that is done, the script will prompt you for the Client Secret for your Command SaaS deployment. The Client Secret can be found on the Orchestrators screen in the Keyfactor Command SaaS Portal for the deployment being configured.

Paste the Client Secret value into the script using the PowerShell Edit > Paste method in the terminal window.

image-20240314-014650.png

Ensure that the password is the full-length secret pasted into the window. The password will have an obfuscated character for each pasted character.

image-20240314-014812.png

If you selected Option 2

If you selected Option 2, the script will prompt you for the credentials to run the service as.

image-20240314-184006.png

Once the credential request is complete, paste your Client Secret using the PowerShell Edit > Paste method in the terminal window.

image-20240314-014650.png

If you selected Option 3

Option 3 will ask for the Client Secret and will then confirm whether to run the Universal Orchestrator in the existing window.

image-20240314-180753.png

You will then see output from the Universal Orchestrator runtime that shows it connected back to Command SaaS.

image-20240314-180920.png

Linux Installation

Step 1

Start by copying the Universal Orchestrator to the Linux server you wish to run the Universal Orchestrator on. Use a command such as the following to SCP the file to the host.

BASH
scp ~/Downloads/KeyfactorUniversalOrchestrator-11.2.0.zip username@<IP_ADDRESS>:/home/username/KeyfactorUniversalOrchestrator-11.2.0.zip

If you are using public key-based authentication to your server, it would resemble the following command.

BASH
scp -i ~/.ssh/public_key.pem ~/Downloads/KeyfactorUniversalOrchestrator-11.2.0.zip username@<IP_ADDRESS>:/home/username/KeyfactorUniversalOrchestrator-11.2.0.zip

Step 2

Use the same command to SCP the SetupOrchestrator_{deploymentName}.sh script to the server. Alternatively, use vi, vim, or nano to create a new file and paste the contents into the file. Add execute permissions to the file once it is created.

CODE
chmod +x SetupOrchestrator_{deploymentName}.sh

Step 3

Ensure that the SetupOrchestrator_{deploymentName}.sh and the UniversalOrchestrator .zip file are in the same directory.

Step 4

Run the SetupOrchestrator_{deploymentName}.sh script.

CODE
./SetupOrchestrator_{deploymentName}.sh

The first thing the script will do is check for and install any dependencies that it needs to run. For additional information on the UO installation requirements, refer to the documentation.

Step 5

Next, it will try to connect to the Command SaaS deployment. If the connection fails, it is likely because it is required to allow any addresses into the Command SaaS deployment via the Self-Service Source IP feature of the Command SaaS Portal. If this happens, run the command to get your outbound IP address and add the following command to the Portal.

CODE
curl ifconfig.me
image-20240315-000342.png

Step 6

The script will then detect your OS version and install .NET Core and any other required dependencies. Once done, the script will ask you for your Client Secret to access your Command SaaS deployment. Copy and paste the Client Secret into the terminal, and then press Enter.

image-20240315-024228.png

Step 7

You should then see a message telling you to go to the Command Portal to approve the Universal Orchestrator.

image-20240315-024319.png

Approving the Universal Orchestrator in Command

Once successfully installed, return to Command SaaS and access OrchestratorsManagement.

image-20240314-181103.png

This will show the new Universal Orchestrator.

image-20240314-181129.png

Right-click the Orchestrator, and then select Approve from the menu.

image-20240314-192643.png

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.