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 (for example 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 a Linux server, copy the zip file containing installation files to a temporary working directory on the Linux server and unzip it.
To begin the installation:
- On the Linux machine on which you wish to install the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores., in a command shell change to InstallationScripts subdirectory under the temporary directory where you placed the installation files.
-
Use the chmod command to make the install.sh script file executable. The file ships in a non-executable state to avoid accidental execution. For example:
sudo chmod +x install.sh -
In the command shell, run the install.sh script as root using the following parameters to begin the installation:
--url (Required)
This is the URL of 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, which is installed as part of the Keyfactor Command Services role. If you installed all the Keyfactor Command server roles together, this is the URL of your Keyfactor Command server with /KeyfactorAgents after the server's IP or FQDN (for example, 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 host name The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (for example servername.keyexample.com) and sometimes just as a short name (for example 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. sets the local orchestrator application setting AgentsServerUri to the specified value.This parameter is required.
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 (username and password), you provide a username and password. With token authentication (bearer-token-url, client_id, and client_secret), you provide a client ID and secret that allows the orchestrator to acquire a bearer token. With client certificate authentication (client-auth-certificate and client-auth-certificate-password), 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: username and password
-
Token Authentication: bearer-token-url, client_id, client_secret, and token_lifetime
- Client Certificate Authentication: client-auth-certificate and client-auth-certificate-password
Important: Choosing to use client certificate authentication for the orchestrator may require additional configuration on your Keyfactor Command server. For more information, see:Tip: For information about rotating passwords and client authentication certificates, see Change Service Account Passwords.--username (Basic Authentication)
This is the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command that you created per Create Service Accounts for the Universal Orchestrator. It may be entered either as username@domain (for example, svc_kyforch@keyexample.com) or DOMAIN\\username (for example, KEYEXAMPLE\\svc_kyforch).
This parameter is required if Basic authentication will be used.
This parameter cannot be used in conjunction with the bearer-token-url or client-auth-certificate and client-auth-certificate-password parameters.
--password (Basic Authentication)
This is the password for the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command specified with the username parameter.
Important: TheThis parameter is required if the username parameter is specified.
This parameter cannot be used in conjunction with the bearer-token-url or client-auth-certificate and client-auth-certificate-password parameters.
Important: Your password may be preserved in command history and may be visible on the process listing when providing a password using this parameter. See the --secret-file-path and --secret-std-in parameters for alternatives.--bearer-token-url (Token Authentication)
Specifying this parameter causes the installation to be done using token authentication for the connection to Keyfactor Command. Set this to the URL of the token endpoint for your identity provider. For example:
https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/tokenFor Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation).
This parameter requires that client-id and client-secret also be specified.
This parameter is required if token authentication will be used.
This parameter cannot be used in conjunction with the username and password or client-auth-certificate and client-auth-certificate-password parameters.
--client-id (Token Authentication)
This parameter is used to specify the ID of the identity provider client that should be used to authenticate the session when bearer-token-url authentication is used (see Create Service Accounts for the Universal Orchestrator).
This parameter requires that client-secret also be specified.
This parameter is only supported if the bearer-token-url parameter is specified.
--client-secret (Token Authentication)
This parameter is used to specify the secret of the OAuth client that should be used to authenticate the session when bearer-token-url authentication is used.
Important: TheThis parameter requires that client-id also be specified.
This parameter is only supported if the bearer-token-url parameter is specified.
Important: Your secret may be preserved in command history and may be visible on the process listing when providing a secret using this parameter. See the --secret-file-path and --secret-std-in parameters for alternatives.--token-lifetime (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 client-id and client-secret also be specified.
This parameter is only supported if the bearer-token-url parameter is specified.
The token-lifetime is optional.
--client-auth-certificate (Client Certificate Authentication)
The path and file name on the orchestrator of a PKCS #12
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 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 --service-user) needs read and write permissions on the PKCS #12 file you specify with this parameter.
This parameter requires that client-auth-certificate-password also be specified.
Specifying this parameter sets the local orchestrator application setting CertPath to the specified value.
This parameter cannot be used in conjunction with the bearer-token-url or username and password parameters.
--client-auth-certificate-password (Client Certificate Authentication)
The password for the PKCS #12 file specified with the client-auth-certificate parameter.
Specifying this parameter requires that client-auth-certificate also be specified.
This parameter cannot be used in conjunction with the bearer-token-url or username parameters.
Important: Your password may be preserved in command history and may be visible on the process listing when providing a password using this parameter. See the --secret-file-path and --secret-std-in parameters for alternatives.--secret-file-path (All Authentication Types)
This parameter specifies a path and filename to provide a plain text secret for the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command. For example:
sudo ./install.sh --secret-file-path /opt/apps/my_secret_file [other parameters here]This parameter can be used with the username, client-auth-certificate, or client-id parameter to provide the authentication secret from a file rather than the command line to avoid storing it in command history.
This parameter cannot be used in conjunction with the password, client_secret, or client-auth-certificate-password parameter.
Tip: Be sure to delete your secret file at the conclusion of the installation.--secret-std-in (All Authentication Types)
This parameter allows you to provide a plain text secret via standard in for the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command. For example:
echo "MySuperSecretPassword" | sudo ./install.sh --secret-std-in [other parameters here]This parameter can be used with the username, client-auth-certificate, or client-id parameter to provide the authentication secret from a file rather than the command line to avoid storing it in command history.
This parameter cannot be used in conjunction with the password, client_secret, or client-auth-certificate-password 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.
--auto-registration-pool-id
This parameter specifies the Keyfactor Command reference GUID of the orchestrator pool for automatic registration during installation. Orchestrators registered in this manner are approved automatically.
--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 active 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 Certificate Store Management Extensions.
-
ssl
Only the SSL discovery and monitoring capability will be active and reported to Keyfactor Command.
If the in-place 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 Linux orchestrator, the default capability set is LOG (log fetching).
Important: The Linux orchestrator does not support 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. (remote CA management) or IIS (Windows server certificate store) capabilities due to the Windows-specific nature of the authentication requirements for these methods.--destination
This parameter specifies a location in which to install the orchestrator that is other than the default. The default installation location is:
/opt/keyfactor/orchestratorThis parameter cannot be used in conjunction with the in-place parameter.
--force, -f
Specifying this parameter causes the installation to warn and continue given certain potential problems, including:
-
The local Universal Orchestrator service account does not exist. The default user will be created if force is specified.
-
The local application settings (appsettings.json) file does not exist. A new one will be created if force is specified.
-
A service with either the default service name or the service name specified with the service-suffix 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. See also the what-if parameter.
--in-place
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.
--no-revocation-check
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).
Important: On Linux-based deployments (including containerized installations), certificate validation relies on the OpenSSL-based TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. stack used by .NET. LDAP-based CRL distribution points are not supported in this environment. Certificates that specify only LDAP CRL locations will fail revocation checking during validation.--no-service
This parameter is used to indicate that no service should be created and added to the server's service control manager. The orchestrator will be installed but will need to be started manually or added to the server's service control manager manually.
This parameter cannot be used in conjunction with the service-suffix or service-user parameter.
--orchestrator-name
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 results from a host name lookup for the orchestrator's name.
--service-suffix
This parameter is used to add a suffix to the root service name of keyfactor-orchestrator (for example, instance1 for a resulting service name of keyfactor-orchestrator-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 no-service parameter.
If this parameter is not specified, the default service name of keyfactor-orchestrator-default will be used.
--service-user
This is the local Linux Universal Orchestrator service account that the service will run as (see Create Service Accounts for the Universal Orchestrator. It should be entered as just the user name. Entry of a password for this service account is not required. You may either create this account before running the installation script (or use an existing account) or use the force parameter to generate the account automatically during the installation process.
This parameter cannot be used in conjunction with the no-service parameter.
If this parameter is not specified, the default service account name of keyfactor-orchestrator will be used.
--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.sh file is found. This parameter is used primarily if a copy of the install.sh 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.
--verbose, -v
Specify this parameter to output verbose installation messages.
--what-if
This parameter is used to test the installation command without actually installing to see any errors that might arise and correct them before installing.
Installation Examples
Installation example with expected output using Basic authentication and an auto-registration pool. The password for the svc_kyforch service account is saved in password_file in the current directory and should be removed after installation.
Copyvi password_file
sudo ./install.sh \
--url https://keyfactor.keyexample.com/KeyfactorAgents \
--username svc_kyforch@keyexample.com \
--secret-file-path password_file \
--orchestrator-name appsrvr16-ssl.keyexample.com \
--auto-registration-pool-id aac79ea0-2a57-4ae1-afcb-2c3159b37acf \
--capabilities all \
--force
*******************************************************************
* Checking for required environment dependencies. *
*******************************************************************
.NET Core Runtime version 10.0.0 or later was found.
jq was found on the PATH.
curl was found on the PATH.
Source path /tmp/KeyfactorUniversalOrchestrator does contain the Keyfactor Orchestrator
***********************************************************
* Validating orchestrator configurations. *
***********************************************************
Validating the authentication parameters.
Validating the capabilities configurations.
Validating the installation directory configurations.
Validating the service configurations.
*************************************************************
* Validating authentication configurations. *
*************************************************************
***********************************************************
* Validating installation configurations. *
***********************************************************
*****************************************************
* Configuring orchestrator service. *
*****************************************************
Copying files from /tmp/KeyfactorUniversalOrchestrator to /opt/keyfactor/orchestrator
Setting file permissions and saving app settings
Installing systemd service keyfactor-orchestrator-default
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-orchestrator-default.service → /etc/systemd/system/keyfactor-orchestrator-default.service.
Starting systemd service keyfactor-orchestrator-defaultTip: Use the -v switch to display additional diagnostic information, which can help when troubleshooting errors.Show example command with verbose output.
Installation example with expected output using token authentication, --secret-std-in for the client secret, and custom destination and service names.
Copyecho "WcHlahyku6wmD0a6rjOXClrkz0Jw9sGh" |sudo ./install.sh \
--url https://command.keyexample.com/KeyfactorAgents \
--bearer-token-url https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token \
--client-id Universal-Orchestrator \
--orchestrator-name appsrvr16-ssl2.keyexample.com \
--destination /opt/keyfactor/uo-2 \
--service-suffix uo2 \
--capabilities all \
--force
*******************************************************************
* Checking for required environment dependencies. *
*******************************************************************
.NET Core Runtime version 10.0.0 or later was found.
jq was found on the PATH.
curl was found on the PATH.
Source path /tmp/KeyfactorUniversalOrchestrator does contain the Keyfactor Orchestrator
***********************************************************
* Validating orchestrator configurations. *
***********************************************************
Validating the authentication parameters.
Validating the capabilities configurations.
Validating the installation directory configurations.
Validating the service configurations.
*************************************************************
* Validating authentication configurations. *
*************************************************************
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 1567 100 1458 100 109 43024 3216 --:--:-- --:--:-- --:--:-- 47484
***********************************************************
* Validating installation configurations. *
***********************************************************
*****************************************************
* Configuring orchestrator service. *
*****************************************************
Copying files from /tmp/KeyfactorUniversalOrchestrator to /opt/keyfactor/uo-2
Setting file permissions and saving app settings
Installing systemd service keyfactor-orchestrator-2
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-orchestrator-2.service → /etc/systemd/system/keyfactor-orchestrator-2.service.
Starting systemd service keyfactor-orchestrator-2Installation example with expected output using client certificate authentication. The password for the client certificate is saved in cert_password_file in the current directory.
Copyvi cert_password_file
sudo ./install.sh \
--url https://command.keyexample.com/KeyfactorAgents \
--client-auth-certificate /opt/certs/kyforch.p12 \
--secret-file-path cert_password_file \
--orchestrator-name appsrvr16-ssl.keyexample.com \
--capabilities all \
--force
*******************************************************************
* Checking for required environment dependencies. *
*******************************************************************
.NET Core Runtime version 10.0.0 or later was found.
jq was found on the PATH.
curl was found on the PATH.
Source path /tmp/KeyfactorUniversalOrchestrator does contain the Keyfactor Orchestrator
***********************************************************
* Validating orchestrator configurations. *
***********************************************************
Validating the authentication parameters.
Validating the capabilities configurations.
Validating the installation directory configurations.
Validating the service configurations.
*************************************************************
* Validating authentication configurations. *
*************************************************************
***********************************************************
* Validating installation configurations. *
***********************************************************
*****************************************************
* Configuring orchestrator service. *
*****************************************************
Copying files from /tmp/KeyfactorUniversalOrchestrator to /opt/keyfactor/orchestrator
Setting file permissions and saving app settings
Installing systemd service keyfactor-orchestrator-default
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-orchestrator-default.service → /etc/systemd/system/keyfactor-orchestrator-default.service.
Starting systemd service keyfactor-orchestrator-default - Review the output from the installation to confirm that no errors have occurred.
The script creates a directory, /opt/keyfactor/orchestrator by default, and places the orchestrator files in this directory. Log files are found in /opt/keyfactor/orchestrator/logs by default, though this is configurable (see Configure Logging for the Universal Orchestrator).
The orchestrator service, by default named keyfactor-orchestrator-default.service, should be automatically started at the conclusion of the install and configured to restart on reboot unless you have selected the no-service parameter.
PAM (Privileged Access Management): Controls privileged access by vaulting credentials, enforcing least-privilege/just-in-time access, rotating secrets, and auditing sessions. Across Keyfactor products, PAM protects diverse sensitive operations and secrets—for example certificate stores and CA credentials—via built-in or third-party providers; external integrations are delivered as custom PAM extensions (several published on Keyfactor’s public GitHub). extensions, Was this page helpful? Provide Feedback