Install the Universal Orchestrator on Windows

To install 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. on Windows, copy the zip file containing installation files to a temporary working directory on the Windows server and unzip it.

To begin the installation:

1. On the Windows machine on which you wish to install the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores., open a PowerShell window using the "Run as Administrator" option and change to the temporary directory where you placed the installation files.

2. In the PowerShell window, run the following commands to populate a variable with the user credentials for the Keyfactor Command connect service account (see Create Service Accounts for the Universal Orchestrator) and, if you plan to run the orchestrator as a standard custom service account (rather than the default of Network Service), populate a variable with the user credentials for the Universal Orchestrator service account:

   $credKeyfactor = Get-Credential
   $credService = Get-Credential

   Enter the appropriate username and password when prompted. In these examples, credKeyfactor is used for the for the Keyfactor Command connect service account that the orchestrator uses to connect to Keyfactor Command and credService is used for the Universal Orchestrator service account that the service runs as. Usernames should be given in DOMAIN\username format.

   To avoid being prompted for credentials while using Network Service to run the local service:

   $keyfactorUser = "DOMAIN\mykeyfactorconnectusername"
   $keyfactorPassword = "MySecurePassword"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)

   To avoid being prompted for credentials while using a standard AD service account to run the local service:

   $serviceUser = "DOMAIN\myserviceusername"
   $keyfactorUser = "DOMAIN\mykeyfactorconnectusername"
   $keyfactorPassword = "MyFirstSecurePassword"
   $servicePassword = "MySecondSecurePassword"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)

   To avoid being prompted for credentials while using a group managed service account (gMSA) to run the local service:

   $serviceUser = "DOMAIN\myGMSAserviceusername$"
   $keyfactorUser = "DOMAIN\mykeyfactorconnectusername"
   $keyfactorPassword = "MySecurePassword"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser,(New-Object System.Security.SecureString))
   Tip:  In some cases, you may be using the same service account for both the Universal Orchestrator service account role and the Keyfactor Command connect service account role. If this is the case, you may use a single variable for both passwords in the next step.
   Note:  Group managed service accounts are not supported for use in making the connection to Keyfactor Command.

3. In the PowerShell window, run the install.ps1 script using the following syntax to begin the installation:

   -URL (Required)

   This is the URL to the Agent Services endpoint An endpoint is a URL that enables the API to gain access to resources on a server. on the Keyfactor Command server running the Keyfactor Command Agent Services role. If you installed all the Keyfactor Command server roles together, this is the URL for your Keyfactor Command server with /KeyfactorAgents after the server's IP or FQDN (e.g. https://keyfactor.keyexample.com/KeyfactorAgents). If you choose to use SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. to connect to the Keyfactor Command server, you’ll need to enter a URL that contains a hostname The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). that is found in the SSL certificate.

   This parameter A parameter or argument is a value that is passed into a function in an application. is required.

   Note:  If you've opted to use client certificate authentication for the orchestrator, the value you use for the URL will vary depending on the method you select to implement client certificate authentication. You may choose to route client certificate authentication through a proxy (see Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC), in which case you would use the proxy server name here (whatever name you're using to route traffic through the proxy). You may choose to publish client certificates to Active Directory and access the Keyfactor Command server directly (see Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication with Certificates Stored in Active Directory), in which case you would use the Keyfactor Command server name here.

   Tip:  If your Keyfactor Command server was configured with an alternate virtual directory for the Keyfactor Command Agents Services endpoint, you will need to enter that in the URL rather than /KeyfactorAgents.
   Client Authentication Parameters (Required)

   The Keyfactor Universal Orchestrator supports authenticating to the Keyfactor Command server using either standard authentication (Basic authentication) or client certificate authentication. When you configure the orchestrator, you should configure either standard authentication (WebCredential) and provide a username and password as a PSCredential object or configure client certificate authentication (either ClientCertificateThumbprint or ClientCertificate and ClientCertificatePassword). You cannot configure both types of authentication together.

   One of the following authentication methods is required:

   • WebCredential

   • ClientCertificateThumbprint

   • ClientCertificate and ClientCertificatePassword

   Important:  Choosing a client certificate authentication method for the orchestrator may require additional configuration on your Keyfactor Command server. For more information, see Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication with Certificates Stored in Active Directory, Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC, and Install the Main Keyfactor Command Components on the Keyfactor Command Server(s) in the Keyfactor Command Server Installation Guide.

   Tip:  For information about rotating passwords and client authentication certificates, see Change Service Account Passwords.

   -WebCredential (Required with Basic Authentication)

   This is the credential object of the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command that you created as per Create Service Accounts for the Universal Orchestrator. It is provided as a PSCredential object.

   This parameter is required if Basic authentication will be used.

   This parameter cannot be used in conjunction with the ClientCertificateThumbprint, ClientCertificate, or ClientCertificatePassword parameter.

   -ClientCertificateThumbprint

   The thumbprint of the client authentication certificate used to authenticate to Keyfactor Command created as per Acquire a Certificate for Client Certificate Authentication (Optional). The certificate must have a Client Authentication EKU, have a private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. readable by the account under which the Universal Orchestrator service will run (see -ServiceCredential), and be located in either the orchestrator local machine's personal certificate store (My) or the Universal Orchestrator service account user's (see -ServiceCredential) personal certificate store. If the certificate is stored in the local machine's store, the Universal Orchestrator service account user must be granted permissions to read the private key of the certificate (see the final steps under Acquire a Certificate for Client Certificate Authentication (Optional)).

   You may specify either the thumbprint of the certificate with the ClientCertificateThumbprint parameter or specify a path and password to a PKCS12 file containing the certificate on the orchestrator using ClientCertificate and ClientCertificatePassword. You do not need to specify both a thumbprint and a PKCS12 file; if you do, the certificate stores will take precedence.

   This parameter cannot be used in conjunction with the WebCredential parameter.

   -ClientCertificate

   The path and file name on the orchestrator of a PKCS12 file containing the client authentication certificate used to authenticate to Keyfactor Command created as per Acquire a Certificate for Client Certificate Authentication (Optional). The certificate must have a Client Authentication EKU.

   The account under which the Universal Orchestrator service will run (see -ServiceCredential) needs read and write permissions on the PKCS12 file you specify with this parameter.

   Specifying this parameter requires that ClientCertificatePassword also be specified.

   You may specify either the thumbprint of the certificate with the ClientCertificateThumbprint parameter or specify a path and password to a PKCS12 file containing the certificate on the orchestrator using ClientCertificate and ClientCertificatePassword. You do not need to specify both a thumbprint and a PKCS12 file; if you do, the certificate stores will take precedence.

   This parameter cannot be used in conjunction with the WebCredential parameter.

   -ClientCertificatePassword

   The password for the PKCS12 file specified with the ClientCertificate parameter.

   Specifying this parameter requires that ClientCertificate also be specified.

   This parameter cannot be used in conjunction with the WebCredential parameter.

   -Source

   Specify this parameter to point to a directory containing the installation files other than the directory in which the install.ps1 file is found. This parameter is used primarily if a copy of the install.ps1 file is made in an alternate directory, updated with some customizations, and then used for installation without being copied back to the directory where the remaining installation files are located.

   -Destination

   This parameter specifies a location in which to install the orchestrator that is other than the default. The default installation location is:

   C:\Program Files\Keyfactor\Keyfactor Orchestrator

   This parameter cannot be used in conjunction with the InPlace parameter.

   -InPlace

   This parameter is used to indicate that the installation should occur in the current directory where the install files are located and no files should be copied to another location on the machine.

   This parameter cannot be used in conjunction with the Destination parameter. This parameter is only supported if the Capabilities parameter is set to all.

   -ServiceSuffix

   This parameter is used to add a suffix to the root service name of KeyfactorOrchestrator (e.g. Instance1 for a resulting service name of KeyfactorOrchestrator-Instance1). This is used primarily for implementations where the orchestrator will be installed multiple times on the same server.

   This parameter cannot be used in conjunction with the NoService parameter.

   If this parameter is not specified, the default service name of KeyfactorOrchestrator-Default will be used—with a display name of Keyfactor Orchestrator Service (Default).

   -ServiceCredential

   This is the credential object of the Universal Orchestrator service account the orchestrator service will run as (see Create Service Accounts for the Universal Orchestrator. It is provided as a PSCredential object.

   This parameter cannot be used in conjunction with the NoService parameter.

   If this parameter is not specified, the built-in Network Service account will be used.

   -NoService

   This parameter is used to indicate that no Windows service should be created. The orchestrator will be installed but will need to be started manually or added as a service at a later time.

   This parameter cannot be used in conjunction with the ServiceSuffix or ServiceCredential parameter.

   -OrchestratorName

   Specifying this parameter allows you to override the name the orchestrator would by default use to register itself in Keyfactor Command.

   By default, the orchestrator uses the value of the COMPUTERNAME environment variable.

   -Capabilities

   This parameter is used to specify the capabilities the orchestrator will support if a capability set other than the default set is desired. Supported options are:

   • all

     All the capabilities supported by the orchestrator will be enabled and reported to Keyfactor Command.

   • none

     The orchestrator will be installed with no capabilities and will not be registered with Keyfactor Command. This is primarily used for implementations that will support only custom capabilities (see Installing Custom-Built Extensions and Configuring Script-Based Certificate Store Jobs).

   • ssl

     Only the SSL discovery and monitoring capability will be enabled and reported to Keyfactor Command.

   If the InPlace parameter is specified, this parameter must be set to all.

   If this parameter is not specified, the default set of capabilities for the orchestrator will be used. For the Universal Orchestrator, the default capability set is IIS, CA, FTP and LOG (log fetching).

   One installation of the orchestrator can be enabled with multiple capabilities to perform more than one function, but there are best practices for locating orchestrators that should be considered. For example, Keyfactor recommends against performing the SSL discovery and monitoring function using an orchestrator installed on the main Keyfactor Command server due to the resource requirements of this function and against using the same orchestrator for the SSL function and other functions, again due to the resource requirements. The CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. management function is typically used on remote servers and not collocated with other orchestrator functions.

   -Force

   Specifying this parameter causes the installation to warn and continue on certain potential problems, including:

   • A service with either the default service name or the service name specified with the ServiceSuffix parameter already exists. The service will be overwritten if Force is specified.

   • Either the default installation location or the location specified with the Location parameter is not empty. The install will occur to the specified or default location anyway and files may be overwritten if Force is specified.

   If this parameter is not specified and any of these problems are encountered, the installation will terminate prematurely.

   Installation example with expected output using basic authentication (rather than a client certificate) and Network Service to run the local service:

   $keyfactorUser = "KEYEXAMPLE\svc_kyforch1"
   $keyfactorPassword = "MySecurePassword123!"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
   
   .\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents -WebCredential $credKeyfactor -OrchestratorName websrvr42-IIS.keyexample.com -Capabilities all
   
   Copying files
   Setting configuration data
   Installing Windows Service
   Granting necessary file permissions to NT AUTHORITY\NETWORK SERVICE for configuration file
   Starting service KeyfactorOrchestrator-Default

   Installation example with expected output using basic authentication (rather than a client certificate) and a standard AD service account to run the local service:

   $serviceUser = "KEYEXAMPLE\svc_kyforch1"
   $keyfactorUser = "KEYEXAMPLE\svc_kyforch2"
   $servicePassword = "MyFirstSecurePassword123!"
   $keyfactorPassword = "MySecondSecurePassword456#"
   $secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
   
   .\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents -WebCredential $credKeyfactor -ServiceCredential $credService -OrchestratorName websrvr42-IIS.keyexample.com -Capabilities all
   
   Copying files
   Setting configuration data
   Installing Windows Service
   Granting necessary file permissions to KEYEXAMPLE\svc_kyforch1 for configuration file
   Granting Log on as a Service permission to KEYEXAMPLE\svc_kyforch1
   Starting service KeyfactorOrchestrator-Default

   Installation example with expected output using basic authentication (rather than a client certificate) and an AD gMSA to run the local service:

   $serviceUser = "KEYEXAMPLE\GMSA_kyforch$"
   $keyfactorUser = "KEYEXAMPLE\svc_kyforch"
   $keyfactorPassword = "MySecurePassword123!"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser,(New-Object System.Security.SecureString))
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
   
   .\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents -WebCredential $credKeyfactor -ServiceCredential $credService -OrchestratorName websrvr42-IIS.keyexample.com -Capabilities all
   
   Copying files
   Setting configuration data
   Installing Windows Service
   Granting necessary file permissions to KEYEXAMPLE\GMSA_kyforch$ for configuration file
   Granting Log on as a Service permission to KEYEXAMPLE\GMSA_kyforch$
   Starting service KeyfactorOrchestrator-Default

   Important:  Prior to using a gMSA in the installation, you need to have installed the account on the Universal Orchestrator server using the Install-ADServiceAccount PowerShell command. For example:

   Install-ADServiceAccount -Identity GMSA_kyforch$

   This requires the Active Directory module for Windows PowerShell, which is installed as a feature as part of the Remote Server Administrator Tools.

   Installation example with expected output using client certificate authentication with the certificate stored in the local machine store:

   $serviceUser = "KEYEXAMPLE\svc_kyforch"
   $servicePassword = "MySecurePassword123!"
   $secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
   $credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)
   
   .\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents -ClientCertificateThumbprint 29b21df7403b4afe6daf44762e5c47fb73c07ce7 -ServiceCredential $credService -OrchestratorName websrvr42-IIS.keyexample.com -Capabilities all
   
   Copying files
   Setting configuration data
   Installing Windows Service
   Granting necessary file permissions to KEYEXAMPLE\svc_kyforch for configuration file
   Granting Log on as a Service permission to KEYEXAMPLE\svc_kyforch
   Starting service KeyfactorOrchestrator-Default

   Tip:  The client certificate authentication example shown here references a certificate stored in the local machine store. Because of this, the service account that will run the Universal Orchestrator service needs to be granted permissions to read the private key of the certificate before the installation is run. If the certificate had been acquired into the Universal Orchestrator service account user's personal store rather than the local machine store, the step of granting private key read permissions would not have been necessary.

   Installation example with expected output using client certificate authentication with the certificate stored as a file:

   .\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents -ClientCertificate C:\Certs\kyforch.pfx -ClientCertificatePassword MySecurePassword123! -OrchestratorName websrvr42-IIS.keyexample.com -Capabilities all
   
   Copying files
   Setting configuration data
   Installing Windows Service
   Granting necessary file permissions to KEYEXAMPLE\svc_kyforch for configuration file
   Granting Log on as a Service permission to KEYEXAMPLE\svc_kyforch
   Starting service KeyfactorOrchestrator-Default

   Tip:  The client certificate authentication example shown here does not use the -ServiceCredential parameter. This will cause the Universal Orchestrator service to run as Network Service. If you prefer to run the service as a domain service account, you will need to include the -ServiceCredential parameter and specify the PSCredential value for the service credentials appropriately, as shown in the previous examples.

   Network Service will need to be granted read and write permissions on the PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. file before the script is executed.

4. Review the output from the installation to confirm that no errors have occurred.

The script creates a directory, C:\Program Files\Keyfactor\Keyfactor Orchestrator by default, and places the orchestrator files in this directory. Log files are found in C:\Program Files\Keyfactor\Keyfactor Orchestrator\logs by default, though this is configurable (see Configure Logging for the Universal Orchestrator).

The orchestrator service, by default given a display name of Keyfactor Orchestrator Service (Default), should be automatically started at the conclusion of the install and configured to restart on reboot unless you have selected the NoService parameter.