Although Client Management includes a built-in SSL certificate which can be used to encrypt communications between agents and the console, installing own SSL certificate is recommended in order to prevent unauthorized devices and consoles from accessing  Client Management infrastructure. When using either the built-in certificate or own certificate, one may see an untrusted certificate warning when accessing the Agent Web interface.

To prevent these warnings, the certificate used by Client Management needs to be imported as described in this article:

SSL certificate warnings may be displayed when accessing the Asset Core agent web interface pages

Generate Certificate

NOTE: The steps for generating a new certificate included in this article are intended as an example, and the support team would not be able to offer further assistance with the creation of the SSL certificate. In this example, OpenSSL is used to generate the SSL certificate, however, the certificate can be generated using any certificate generation utility. Please consult the documentation of the certificate generation tools for further information on the use of these tools. If a different certificate generation tool is being used, please note that the certificate required by the Client Management agent must be a CA-type certificate (the Client Management agent handles generating individual certificates for each agent) in order to use the process below for certificate installation.

NOTE: Although it is possible to use a certificate issued by a public, trusted certificate authority (such as Verisign or Thawte), purchasing a CA-type certificate from one of these certificate authorities is often much more costly than a standard SSL certificate.

Using OpenSSL to generate a new root CA certificate:

1. If using a Windows system to generate the certificate, then download and install OpenSSL here. For Linux systems, OpenSSL may already be installed, though if it is not, consult the distributor's documentation for installation instructions.

2. Use the following commands to generate a new private key, and a new root CA certificate:

   openssl genrsa -des3 -out mycert.key.secure 1024 openssl req -new -x509 -days 365 -key mycert.key.secure -out mycert.crt

3. Remove the password from the private key, as the Client Management agent does not have a way of prompting forthis password. The agent will secure the public key during the certificate import process. Use the following command to remove the password and store the new key in a different file:

   openssl rsa -in mycert.key.secure -out mycert.key

    

NOTE: The .crt and .key files must have the same base filename. In other words, if the certificate file is named "mycert.crt", the private key file must be named "mycert.key" NOTE: Unless otherwise noted, all steps which mention copying the .crt or .key files should use the files generated by OpenSSL; copies of the certificate files which have been processed by the Client Management agent (i.e. the copies of the files from the \bin\certs\ agent directory) have been encrypted by the agent, and cannot be used to construct the below-described package, or used as post-install files in rollouts. Installing the certificate into Client Management will require the mycert.crt and mycert.key files generated with these commands. Any other files generated by openssl will not be used in this example.

Install the certificate in a new environment (only the master agent is installed)

Note that the steps below assume that the master server is already configured to use SSL connections with the built-in certificate. 

1. Stop the Client Management agent service on the master server.

2. Navigate to the directory where the master agent has been installed. This is typically \Program Files\BMC Software\Client Management\Master\.

3. Copy the .crt and .key file for the certificate into the .\Master\bin\certs\auth\ directory.

4. Copy the .crt file for the certificate into the .\Master\bin\certs\trusted\ directory.

5. Copy the .crt file for the ertificate into the .\Master\ui\console\jws\certs\trusted\ directory. This will configure the console on the master server to trust the new certificate. See the sections titled "Installing the certificate for the MSI installed console" and "Installing the certificate for the Java Web Start console" for instructions for this process for copies of the console installed on other systems.

6. Open the .\Master\config\mtxagent.ini file using any text editor.

7. Set the CertAuth and CertTrusted parameters in this mtxagent.ini file to the name of the certificate filed (without extensions). For example, if  certificate files are named "mycert.crt" and "mycert.key", these parameters in the INI should be set to "mycert"

8. Start the Client Management agent on the master server.

9. Follow the steps in the "Including the certificate in agent rollouts" section below to include the certificate for newly installed agents, as this certificate will be needed to allow agents to communicate with the master.

Install the certificate in the existing environment (already has relays/clients)

Please note that the steps below assume that the master server is already configured to use SSL connections with the built-in certificate. If the master server is not yet configured for SSL, please follow the steps in this article before proceeding. When installing a new SSL certificate in an environment with existing client devices, a total of 3 operational rules are required to ensure that agent communication is not interrupted. The necessary rules are:

1. A rule which contains a package with the required certificate files, and a step to configure the agent to trust both the existing certificate and the new one. After this, the agent will use the existing certificate to encrypt communications and accept connections from devices using either the existing certificate or the new one.

2. A rule which configures the agent to use the new certificate to encrypt communications. After this, the agent will use the new certificate to encrypt communications and accept connections from devices using either the existing certificate, or the new one.

3. A rule which removes the existing certificate from the trusted certificates list. After this, the agent will use the new certificate to encrypt communications and will only accept connections from devices using the new certificate.

Please follow the steps below to install the new certificate on the master, and create the required operational rules:

1. Stop the Client Management agent service on the master server.

2. Navigate to the directory where the master agent has been installed. This is typically \Program Files\BMC Software\Client Management\Master\.

3. Copy the .crt and .key file for the certificate into the .\Master\bin\certs\auth\ directory.

4. Copy the .crt file for the certificate into the .\Master\bin\certs\trusted\ directory.

5. Copy the .crt file for the certificate into the .\Master\ui\console\jws\certs\trusted\ directory. This will configure the console on the master server to trust the new certificate. See the sections titled "Installing the certificate for the MSI installed console" and "Installing the certificate for the Java Web Start console" for instructions for this process for copies of the console installed on other systems.

6. Open the .\Master\config\mtxagent.ini file using any text editor.

7. Locate the CertTrusted parameter under the Security section.

   1. If this parameter has an existing value, append the name of the new certificate to the existing entry, separated by a comma. For example, if the certificate files are named "mycert.crt" and "mycert.key" and the existing line reads "CertTrusted=bcm", this parameter should be set to "CertTrusted=bcm,mycert"

   2. If there is no existing value in this parameter, add the name of the new certificate and "amp" separated by a comma. For example, if the certificate files are named "mycert.crt" and "mycert.key", this parameter should be set to "CertTrusted=mycert, amp"

8. Make a note of the values for the CertAuth and CertTrusted parameters; these will be needed while building the package to install the certificate on the clients.

9. Start the agent service on the master server.

10. Create a package and operational rule to deploy the new certificate files to relays and clients

    1. On the master server, navigate to a temporary folder (such as c:\temp for example), and create directories named "auth" and "trusted".

    2. Copy the .crt and .key file for the certificate into the .\auth\ directory.

    3. Copy the .crt file for the certificate into the .\trusted\ directory.

    4. In the console, click Wizards > Package Creation to start the new package wizard. Select the master as the package factory and select Custom Package as the type.

    5. On the next screen, enter a name for the package, and ensure the Installation Options and Add Files options are checked.

    6. On the Installation Options page in the wizard, enter "./certs" (without the quotes) for the Destination Path. Leave the remaining options on this page in the default settings.

    7. On the Add Files page, click the add button near the top of the window, then select the auth and trusted folders created in step 4 above. Please ensure that the "Enable Full Path" option at the bottom of the file browser window is not checked.

    8. On the Publication page, select publish the package to the master server, and click finish.

    9. After completing the package creation wizard,  it will prompt to start a new wizard. Select the option to "Create an Operational Rule" and click OK.

    10. In the Operational Rule Creation wizard, enter a name for the rule if desired (by default, the rule will be named based on the name of the package), and click next.

    11. On the Steps tab, click the add button, and add the Agent Parameter Setup step (this step can be found under the Agent Configuration folder). Set the parameters of the step as follows:

        1. ensure that Access Control and Secure Communication are both set to yes.

        2. For the Authority Certificate parameter, enter the same value as the CertAuth parameter from the master server's mtxagent.ini (see step 8 above)

        3. For the Trusted Authorities parameter, enter the same value as the CertTrusted parameter from the master server's mtxagent.ini

        4. The User Certificate field should be left blank

        5. the remaining options can be set as desired.

    12. Add the Restart Agent step to this rule as well. The rule should now contain 3 steps in the following order Install Package (this is added automatically), Agent Parameter Setup, and Restart Agent.

11. Assign this operational rule to all client and relay devices.

12. Once all devices have executed the rule to install the certificate files, create an operational rule to configure devices to use the new certificate when generating the agent certificate.

    1. With any Operational Rule folder selected on the left side of the console window, right-click the right side of the console window, and select "Create Operational Rule".

    2. Enter a name for this new rule, and click OK.

    3. From the rule created in step 11 above, copy the Agent Parameter Setup and Restart agent steps into the newly created rule

    4. Double-click the Agent Parameter Setup step, and on the Authority Certificate line, enter the name of the new certificate. For example, if the filename for the new certificate is "mycert.crt" please enter "mycert".

    5. Ensure the Trusted Authorities parameter also includes this certificate name (it should already be present, as the step was copied from the previous rule). Do not remove any items from this parameter at this time.

13. Assign this rule to all devices, including the master server.

14. Once all devices have executed this rule, create a rule to prevent the built-in certificate from being used for agent communication

    1. With any Operational Rule folder selected on the left side of the console window, right-click the right side of the console window, and select "Create Operational Rule".

    2. Enter a name for this new rule, and click OK.

    3. From the rule created in step 13 above, copy the Agent Parameter Setup and Restart agent steps into the newly created rule

    4. Double-click the Agent Parameter Setup step, and for the Trusted Authorities parameter, ensure that the new certificate name is the only entry. For example, if the certificate file is named "mycert.crt", enter "mycert" for this parameter.

15. Assign this rule to all devices, including the master server.

16. Follow the steps in the "Including the certificate in agent rollouts" section below to include the certificate for newly installed agents, as this certificate will be needed to allow agents to communicate with the master.

Including the certificate in agent rollouts

In order for client devices to be able to communicate with the master server, they must use a certificate that the master agent trusts, it is a must to include the .crt and .key files in agent rollouts as described below:

1. Ensure that the .crt and .key files for the certificate are available on the master server. These files can be in any location on the master.

2. Start the Agent Rollout by clicking Wizard Wizards > Agent Rollout in the console.

3. On the first screen in the wizard, ensure that the "Execute a post-installation script or add files to client agents" and "Configure different secure communication settings on the client agents than the master" options are selected. Optionally, check any other options as required for the desired configuration. The remainder of these instructions assumes that these are the only options checked.

4. Fill in the fields on the General Parameters tab as desired

5. On the Security step in the wizard, ensure the Authority Certificate and Trusted Authorities fields show the name of the certificate. For example, if the filename for the certificate is "mycert.crt", these fields should read "mycert".

6. the Post-Install step in the wizard, click the Add button under the Files section

7. Browse for the .crt file for the certificate. When prompted for a destination path enter "./bin/certs/trusted" (without the quotes).

8. Browse for the .crt file for the certificate again. When prompted for a destination path enter "./bin/certs/auth" (without the quotes).

9. Browse for the .key file for the certificate. When prompted for a destination path enter "./bin/certs/auth" (without the quotes).

10. Proceed through the remainder of the rollout wizard as usual.

If it is required to modify an existing rollout, rather than create a new one, the certificate files can be added as described above on the Files tab under the Post-Install node of the rollout. Also, ensure the certificate file name (with no extension) has been added to the Authority Certificate and Trusted Authorities parameters under the Agent Configuration > Security node for the rollout. After adding the files, and making the required security configuration changes, please expand the Servers node under the rollout, and for each listed rollout server, please right-click the server's name, and click Generate Rollout Package. This will ensure that the rollouts have been updated on each rollout server to include the certificate files.

Install cert for Java Web Start console (11.7 and earlier)

In order to login with the Client Management console after installing the own certificate for the master, it is a must to configure the console to trust the new certificate using the steps below.

1. If the console is already installed, skip to step 2.

   1. go to https://MASTER:1610/console, and click the Java Web Start button to install the Java Web Start console

   2. Depending on the browser, double-click the console.jnlp file downloaded from this page (some browsers will launch this automatically).

   3. When the login window is displayed, click the Cancel button to close the console (complete the below steps to install the certificate before login)

2. Navigate to the %appdata%\Numara AMP\ directory (on a Windows 7 system, this will be equivalent to c:\users\%USERNAME%\AppData\Roaming\Numara AMP\). There should be a file named ConsoleState.properties.

3. Create a folder named "certs", then create a folder named "trusted" inside the certs folder

4. Copy the .crt file into the %appdata%\Numara AMP\certs\trusted\ directory

Install cert for Java Web Start console (12.0 and later)

Starting with version 12.0, the Java Web Start console download will include the required certificate for new installations of the console. If the Java Web Start console had been installed prior to installing the new certificate, the updated certificate can be installed as described in the above section for version 11.7 and earlier, or go to the master's console page (https://MASTER:1610/console) to download an updated JNLP file which includes the new certificate.

Install cert for MSI installed console

In order to log in with the Client Management console after installing own certificate for the master, one must also configure the console to trust the new certificate using the steps below.

1. If the console is already installed, skip to step 2.

   1. go to https://MASTER:1610/console, and click the appropriate link under the Default Installation Packages section

   2. Extract the contents of the zip file downloaded above

   3. From the directory where this zip file was extracted, run the appropriate setup batch file (depending on the language). For example, for English, run the "setup_en.bat" file

2. Navigate to the directory where the MSI version of the console has been installed. Typically, this will be the \Program Files\BMC Software\Client Management\Console\ directory. This directory should contain a file named "NumaraFootPrintsAssetCore.jar".

3. Create a folder named "certs", then create a folder named "trusted" inside the certs folder

4. Copy the .crt file into the \Program Files\BMC Software\Client Management\Console\certs\trusted\ directory