Install the Java Agent on Windows

The Keyfactor Java AgentClosed The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed. installation script offers the option to install the Java agent directly or use the installation script to build an msi package that you can then use to install the Java agent on multiple machines.

Note:  If you have a previously installed version of the Keyfactor Java Agent on this server, you need to uninstall it (see Uninstall the Java Agent) before installing a new version.

To begin the Java agent installation on Windows, unzip the installation files and place them in a temporary working directory.

  1. On the Windows machine on which you wish to install the Java agent or build the package, 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 cms-java-agent-installer.bat file to begin the installation. You will be prompted to answer several questions:

    This is the service account on the Keyfactor Command server side of the fence you created as per Create Service Accounts for the Java Agent. It should be entered in the format DOMAIN\username.

    This is the password for the service account on the Keyfactor Command server side of the fence.

    This is the FQDN or IP address of 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 FQDN or IP address of your Keyfactor Command server.

    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 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). at this prompt that is found in the SSL certificate.

    If you're using a non-standard port for IIS on your Keyfactor Command server, enter that here as part of your hostname or IP address (e.g. keyfactor.keyexample.com:444).

    Press Enter to accept the default of KeyfactorAgents. Only enter an alternate virtual directory if your Keyfactor Command server was configured with an alternate virtual directory for the Keyfactor Command Agents service.

    Press Enter to accept the default of Yes or enter No. The following instructions assume that you answered Yes.

    If your Keyfactor Command server is using a publicly rooted certificate, the server most likely already trusts the certificate issuer, and you can press Enter here.

    If the certificate on the Keyfactor Command server was internally generated, you will need to enter the full path and file name pointing to a file on the local server containing the PEMClosed A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key.-encoded root certificate for the certificate authorityClosed 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. chain that issued the certificate (see Configure Certificate Root Trust for the Java Agent).

    The root certificate will be saved in a Java keystore file called trust.jks located in the Java agent’s install directory (C:\Program Files\Keyfactor\Keyfactor Java Agent by default). The default keystore password is "changeit". Please contact Keyfactor technical support for assistance in changing the default password, if desired.

    This question will not appear if you answered no to the question about using SSL.

    Press Enter to accept the default of "Yes". The Java agent will attempt to connect to the Keyfactor Command server using the credentials provided to confirm that the server name, agents URL, root trust, and provided credentials are valid. Enter "No" to skip this validation if you don't have connectivity to the Keyfactor Command server at the time of installation.

    Tip:  If the installer terminates after this question without an error or with an error writing the trust.jks file, it can be an indication that the path to the root certificate you provided in the previous question was incorrect in some way (e.g. the path is not valid, the root certificate doesn't match the certificate on the Keyfactor Command server, etc.)

    The options at this prompt are "local" or "msi". If you press enter to accept "local", the Java agent will be installed locally. If you enter "msi", the batch file will generate an msi after all the questions have been answered. You can use this to install the Java agent on other Windows systems with the installation questions already answered. The subsequent questions differ depending on the answer given to this question. The following instructions include both local and msi questions. You will not see all of these questions.

    If you select "msi", the Java agent will not be installed locally.

    Press Enter to accept the default installation directory of C:\Program Files\Keyfactor\Keyfactor Java Agent or enter an alternate path if desired. This question does not appear when generating an msi.

    Press Enter to accept the default of the local SYSTEM account for local installs (this is not an option when generating an msi) or enter a specific user account—the service account for the Java agent side of the fence you created as per Create Service Accounts for the Java Agent. Domain user accounts should be entered in the format DOMAIN\username. You do not need to enter the password for this user at this time. The username is entered at this time to allow permissions to be configured appropriately.

    Press Enter to accept the default of the local machine's hostname as determined by a reverse DNSClosed The Domain Name System is a service that translates names into IP addresses. lookup or, failing that, the value of the local environment variable for the computer name. If desired, you can enter an alternative value to use as the hostname. This is the identifier for the server on which you are installing the Java agent. This identifier can be in the form of a hostname or FQDN, but you can use another unique identifier, if desired. This identifier appears in the Keyfactor Command Management Portal on the orchestrators page. This question does not appear when generating an msi.

    Tip:  When installing from an msi, you can specify a custom hostname by using the AGENTNAME parameterClosed A parameter or argument is a value that is passed into a function in an application.. In order to use this option, you must install the msi from the command line. For example:

    msiexec /i C:\temp\cms-java-agent.msi AGENTNAME=jvagnt38.keyexample.com

    Note:  If the agent machine has a non-private address, you will most likely need to use this option.

    Press Enter to accept the default log directory of C:\CMS\logs or enter an alternate path if desired. This question does not appear when generating an msi.

    Press Enter to accept the default of 7 log files or enter an alternate number if desired. Older files are automatically deleted once more files than this have been generated.

    Press Enter to accept the default log file size of 3 MB or enter an alternate value if desired.

    Press Enter to accept the default value and begin the installation. If you would like to install one or more Any Agent implementations, enter yes. In this case, you’ll be presented with a list of custom certificate store types for which to provide an implementation. After choosing each one, you’ll need to enter the path to the .jar file that implements the certificate store type. That .jar file will be copied to the installation directory, under the libs folder. You’ll need to manually copy any other dependent .jar files to that location as well. Note that this option is only available when the Java agent is installed locally. This question does not appear when generating an msi.

  3. After answering the AnyAgentClosed The AnyAgent, one of Keyfactor's suite of orchestrators, is used to allow management of certificates regardless of source or location by allowing customers to implement custom agent functionality via an API. components question, the installation begins. Review the output to be sure that no errors have occurred and then press any key to return to the PowerShell prompt.

    Figure 543: Keyfactor Java Agent Local Installation on Windows

  4. In the PowerShell window, change to the install directory within the directory in which you installed the Java agent. If you installed in the default install directory, this path is:

    C:\Program Files\Keyfactor\Keyfactor Java Agent\install

  5. In the PowerShell window, run the install.ps1 PowerShell script. Unless you selected SYSTEM as the user the agent should run as, you will be prompted to enter the username (DOMAIN\username format) and password of the account that will run the Keyfactor Java Agent service on the local machine. This is the service account for the Java agent side of the fence you created as per Create Service Accounts for the Java Agent. Press Enter without entering any data to run the service under the local system credentials.

    Note:  The install.ps1 may fail with an error similar to the following on older versions of Windows:
    Method invocation failed because [System.Object[]] doesn't contain a method named 'Replace'.

    If this occurs, you need to manually grant the service account under which the Keyfactor Java Agent service will run the local "Log on as a service" permission and then run the install.ps1 script again.

Tip:  If you choose the "msi" option rather than the "local" option, the MSI file will be generated in the directory in which you executed the batch file.