Install the Universal Orchestrator on a Linux Server

To install 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. 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:

  1. On the Linux machine on which you wish to install the orchestratorClosed 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.

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

  3. In the command shell, run the install.sh script as root using the following parameters to begin the installation:

    This is the URL to the Agent Services endpointClosed 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 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 SSLClosed 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 hostnameClosed 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 parameterClosed 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.

    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 Install the Keyfactor Command Components on the Keyfactor Command Server(s) in the Keyfactor Command Server Installation Guide and 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.
    Tip:  For information about rotating passwords and client authentication certificates, see Change Service Account Passwords.

    This is 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 may be entered either as username@domain (e.g. svc_kyforch@keyexample.com) or DOMAIN\\username (e.g. 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.

    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:  The password for the Keyfactor Command connect service account is stored in clear text in the orchestratorsecrets.json file in the configuration directory under the installation directory for the orchestrator. By default, this file is granted read/write permissions for the Universal Orchestrator service account running the service on the Linux machine (keyfactor-orchestrator by default) and no permissions for any other users. Access to this file should be strictly controlled.

    If you prefer to avoid the use of a password in a file, consider using client certificate authentication.

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

    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/token

    For Keyfactor Identity Provider, 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 Keyfactor Identity Provider 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.

    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.

    This parameter is used to specify the secret of the Keyfactor Identity Provider client that should be used to authenticate the session when bearer-token-url authentication is used.

    Important:  The client secret for the Keyfactor Command connect service account is stored in clear text in the orchestratorsecrets.json file in the configuration directory under the installation directory for the orchestrator. By default, this file is granted read/write permissions for the Universal Orchestrator service account running the service on the Linux machine (keyfactor-orchestrator by default) and no permissions for any other users. Access to this file should be strictly controlled.

    If you prefer to avoid the use of a password in a file, consider using client certificate authentication.

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

    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.

    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 --service-user) needs read and write permissions on the PKCS12 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.

    The password for the PKCS12 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.

    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.

    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.

    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.

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

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

    /opt/keyfactor/orchestrator

    This parameter cannot be used in conjunction with the in-place parameter.

    Specifying this parameter causes the installation to warn and continue on 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.

    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.

    This parameter is used to indicate that the revocation status (CRLClosed 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).

    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.

    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 hostname lookup for the orchestrator's name.

    This parameter is used to add a suffix to the root service name of keyfactor-orchestrator (e.g. 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.

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

    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.

    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.

    Specify this parameter to output verbose installation messages.

    This parameter is used to test the installation command without actually installing in order to see any errors that might arise and correct them before installing.

    Installation example with expected output using Basic authentication (the password for the svc_kyforch service account is saved in my_password_file):

    vi my_password_file

    sudo ./install.sh --url https://keyfactor.keyexample.com/KeyfactorAgents --username svc_kyforch@keyexample.com --secret-file-path my_password_file --orchestrator-name appsrvr16-ssl.keyexample.com --capabilities all --force

    Creating user keyfactor-orchestrator
Copying files from /tmp/KeyfactorOrchestrator to /opt/keyfactor/orchestrator
Saving app settings
Setting file permissions
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

    Installation example with expected output using token authentication (the secret for the client is provided at standard in):

    echo "WcHlahyku6wmD0a6rjOXClrkz0Jw9sGh" | sudo ./install.sh --url https://keyfactor.keyexample.com/KeyfactorAgents --bearer-token-url https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token --client-id Universal-Orchestrator --secret-std-in --orchestrator-name appsrvr16-ssl.keyexample.com --capabilities all --force

    Creating user keyfactor-orchestrator
Copying files from /tmp/KeyfactorOrchestrator 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

    Installation example with expected output using client certificate authentication (the password for the client certificate is saved in cert_password_file):

    vi cert_password_file

    sudo ./install.sh --url https://keyfactor.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

    Creating user keyfactor-orchestrator
Copying files from /tmp/KeyfactorOrchestrator to /opt/keyfactor/orchestrator
Saving app settings
Setting file permissions
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
  4. 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.

Tip:  Once the installation of the orchestrator is complete, you need to use the Keyfactor CommandManagement Portal to approve the orchestrator and configure certificate stores or SSL jobs: