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 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 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 InstallationScripts subdirectory under the temporary directory where you placed the installation files.

2. In the PowerShell window, populate variables as appropriate based on the identity provider you’re using for Keyfactor Command, the desired orchestrator service accounts, and the desired install experience to prepare for the install. See the installation examples, below.

   In the below examples, the following variables are shown:

   • $credKeyfactor: This is used for the Keyfactor Command connect service account when the orchestrator uses Basic authentication to connect to Keyfactor Command. This is populated either using Get-Credential or built using $keyfactorUser, $keyfactorPassword, and $secKeyfactorPassword.
   • $credService: This is used for the Universal Orchestrator service account that the service runs as. Usernames should be given in DOMAIN\username format for Active Directory domain accounts or 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).\username format for local user accounts. This is populated either using Get-Credential or built using $serviceUser, $servicePassword (as appropriate), and $secServicePassword (as appropriate).
   • $secClientSecret: This is used for the Keyfactor Command connect service account when the orchestrator uses OAuth token authentication to connect to Keyfactor Command. This is populated using either a Read-Host masked input prompt or built using $clientSecret.
   • $secCertPassword: This is used for the Keyfactor Command connect service account when the orchestrator uses client certificate authentication to connect to Keyfactor Command. This is populated using either a Read-Host masked input prompt or built using $certPassword.
   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.

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 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. sets the local orchestrator application setting AgentsServerUri to the specified value.

   This parameter 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).

   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 Basic authentication, token authentication, or client certificate authentication. The method you choose depends in part on the identity provider in use for the Keyfactor Command the orchestrator will be communicating with. If you’re using Active Directory as an identity provider, you may choose Basic authentication or client certificate authentication. If you’re using an identity provider other than Active Directory, you may choose token authentication or client certificate authentication.

   When you configure the orchestrator with Basic authentication (WebCredential), you provide a username and password as a PSCredential object. With token authentication (BearerTokenUrl), you provide a client ID and secret that allows the orchestrator to acquire a bearer token. With client certificate authentication (either ClientCertificateThumbprint or ClientCertificate and ClientCertificatePassword), the orchestrator uses a client certificate to authenticate to either a proxy or IIS on the Keyfactor Command server. You cannot configure multiple types of authentication together.

   One of the following authentication methods is required:

   • Basic Authentication: WebCredential

   • Token Authentication: BearerTokenUrl, ClientId, ClientSecret, and TokenLifetime

   • Client Certificate Authentication: ClientCertificate and ClientCertificatePassword

   • Client Certificate Authentication: ClientCertificateThumbprint

   Important:  Choosing to use client certificate authentication for the orchestrator may require additional configuration on your Keyfactor Command server. For more information, see:

   • Install Keyfactor Command on a Windows Server Under IIS
   • Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication Directly
   • Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC

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

   -WebCredential (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 BearerTokenURL, ClientCertificateThumbprint, ClientCertificate, or ClientCertificatePassword parameter.

   -BearerTokenURL (Token Authentication)

   Specifying this parameter causes the installation to be done using token authentication for the connection to Keyfactor Command.

   This parameter requires that ClientId and ClientSecret also be specified.

   This parameter is required if token authentication will be used.

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

   -ClientId (Token Authentication)

   This parameter is used to specify the ID of the identity provider client that should be used to authenticate the session when BearerTokenUrl authentication is used (see Create Service Accounts for the Universal Orchestrator).

   This parameter requires that ClientSecret also be specified.

   This parameter is only supported if the BearerTokenUrl parameter is specified.

   -ClientSecret (Token Authentication)

   This parameter is used to specify the secret of the identity provider client that should be used to authenticate the session when BearerTokenUrl authentication is used. It is provided as a SecureString.

   This parameter requires that ClientId also be specified.

   This parameter is only supported if the BearerTokenUrl parameter is specified.

   -TokenLifetime (Token Authentication)

   The number of seconds for which the bearer token is valid. If not specified, the orchestrator uses the default value set by the Keyfactor Command server of 300 seconds (5 minutes).

   This parameter requires that ClientId and ClientSecret also be specified.

   This parameter is only supported if the BearerTokenUrl parameter is specified.

   The TokenLifetime is optional.

   -ClientCertificate (Client Certificate Authentication)

   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.

   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.

   Specifying this parameter sets the local orchestrator application setting CertPath to the specified value.

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

   -ClientCertificatePassword (Client Certificate Authentication)

   The password for the PKCS12 file specified with the ClientCertificate parameter. It is provided as a SecureString.

   Specifying this parameter requires that ClientCertificate also be specified.

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

   -ClientCertificateThumbprint (Client Certificate Authentication)

   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.

   Specifying this parameter sets the local orchestrator application setting AuthCertThumbprint to the specified value.

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

   -Audience

   This parameter is used to specify an audience value to be included in token requests delivered to the identity provider when using an identity provider other than Active Directory.

   -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.

   • 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 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.

   -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.

   -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.

   -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.

   -NoRevocationCheck

   This parameter is used to indicate that the revocation status (CRL A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted.) of the SSL certificate on the Keyfactor Command server should not be checked when connecting to Keyfactor Command.

   Specifying this parameter sets the local orchestrator application setting CheckServerCertificateRevocation to false. The default for this parameter is true (CRL checking will be done).

   -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.

   Specifying this parameter sets the local orchestrator application setting OrchestratorName to the specified value.

   By default, the orchestrator uses the value of the COMPUTERNAME environment variable for the orchestrator's name.

   -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.

   -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).

   -Scope

   This parameter is used to specify one or more scopes that should be included in token requests delivered to the identity provider when using an identity provider other than Active Directory. Multiple scopes should be separated by spaces.

   -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.

   Refer to the below examples for guidance.

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.

Keyfactor Connect User: Basic Authentication | Service User: Network Service

This example, with expected output, shows using Basic authentication for the Keyfactor connect user 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.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

$credKeyfactor = Get-Credential

Keyfactor Connect User: Basic Authentication | Service User: Active Directory Service Account

This example, with expected output, shows using Basic authentication for the Keyfactor connect user and a standard Active Directory service account to run the local service:

$serviceUser = "KEYEXAMPLE\svc_kyforch1"
$servicePassword = "MyFirstSecurePassword123!"
$secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
$credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)

$keyfactorUser = "KEYEXAMPLE\svc_kyforch2"
$keyfactorPassword = "MySecondSecurePassword456#"
$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 `
  -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

$credKeyfactor = Get-Credential

$credService = Get-Credential

Keyfactor Connect User: Basic Authentication | Service User: Active Directory gMSA

This example, with expected output, shows using Basic authentication for the Keyfactor connect user and an Active Directory gMSA to run the local service:

$serviceUser = "KEYEXAMPLE\GMSA_kyforch$"
$credService = New-Object System.Management.Automation.PSCredential ($serviceUser,(New-Object System.Security.SecureString))

$keyfactorUser = "KEYEXAMPLE\svc_kyforch"
$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 `
  -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

$credKeyfactor = Get-Credential

Keyfactor Connect User: Token Authentication | Service User: Network Service

This example, with expected output, shows using OAuth token authentication for the Keyfactor connect user and Network Service to run the local service:

$clientSecret = "MySecureClientSecret123!"
$secClientSecret = ConvertTo-SecureString $clientSecret -AsPlainText -Force

.\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents `
   -BearerTokenUrl https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token `
   -ClientId Universal-Orchestrator `
   -ClientSecret $secClientSecret `
   -OrchestratorName websrvr42-UO.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

Keyfactor Connect User: Token Authentication | Service User: Local Account

This example, with expected output, shows using OAuth token authentication for the Keyfactor connect user and a local account on the machine to run the local service:

$serviceUser = "websrvr42\kyforch"
$servicePassword = "MySecurePassword123!"
$secServicePassword = ConvertTo-SecureString $servicePassword -AsPlainText -Force
$credService = New-Object System.Management.Automation.PSCredential ($serviceUser, $secServicePassword)

$clientSecret = "MySecureClientSecret123!"
$secClientSecret = ConvertTo-SecureString $clientSecret -AsPlainText -Force

.\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents `
   -BearerTokenUrl https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token `
   -TokenLifetime 150 `
   -ClientId Universal-Orchestrator `
   -ClientSecret $secClientSecret `
   -ServiceCredential $credService `
   -OrchestratorName websrvr42-UO.keyexample.com `
   -Capabilities all

Copying files
Setting configuration data
Installing Windows Service
Granting necessary file permissions to websrvr42\kyforch for configuration file
Granting Log on as a Service permission to websrvr42\kyforch
Starting service KeyfactorOrchestrator-Default

Keyfactor Connect User: Client Certificate Authentication | Service User: Active Directory Service Account

This example, with expected output, shows using client certificate authentication with the certificate stored in the local machine store for the Keyfactor connect user and a standard Active Directory service account to run the local service:

$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

$credService = Get-Credential

Keyfactor Connect User: Client Certificate Authentication | Service User: Network Service

This example, with expected output, shows using client certificate authentication with the certificate stored as a file and Network Service to run the local service:

$certPassword = "MySecureCertPassword123!"
$secCertPassword = ConvertTo-SecureString $clientSecret -AsPlainText -Force

.\install.ps1 -URL https://keyfactor.keyexample.com/KeyfactorAgents `
  -ClientCertificate C:\Certs\kyforch.pfx `
  -ClientCertificatePassword $secCertPassword `
  -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