Installing a new SSL certificate in Client Management[1]

Version 1
    Share:|

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    PRODUCT:

    BMC Client Management


    APPLIES TO:

    BMC Client Management



    PROBLEM:

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

    To prevent these warnings, you would need import the certificate used by Client Management as described in this article:

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


    SOLUTION:

    Generate Certificate

    NOTE: The steps for generating a new certificate included in this article are intended as an example, and our support team would not be able to offer further assistance with the creation of the SSL certificate. In this example, we will use OpenSSL to generate the SSL certificate, however, the certificate can be generated using any certificate generation utility. Please consult the documentation for your certificate generation tools for further information on the use of these tools. If you will be using a different certificate generation tool, please keep in mind 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: Altough 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 you will be using a Windows system to generate the certificate, please download and install OpenSSL here. For Linux systems, OpenSSL may already be installed, though if it is not, please consult your distribution's documentation for installation instructions.
    2.  
    3. 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
    4.  
    5. We must now remove the password from the private key, as the Client Management agent does not have a way of prompting for this 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 your 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 a Client Management agent (i.e. the copies of the files from the \bin\certs\ agent directory) have been encrypted by the agent, and can not 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 certificate in new environment (only master agent is installed)

    Please note that the steps below assume that your master server is already configured to use SSL connections with the built-in certificate. If your master server is not yet configured for SSL, please follow the steps in   this knowledge base article before proceeding.  
       
    1. Stop the Client Management agent service on the master server.
    2.  
    3. Navigate to the directory where the master agent has been installed. This is typically \Program Files\BMC Software\Client Management\Master\.
    4.  
    5. Copy the .crt and .key file for your certificate into the .\Master\bin\certs\auth\ directory.
    6.  
    7. Copy the .crt file for your certificate into the .\Master\bin\certs\trusted\ directory.
    8.  
    9. Copy the .crt file for your 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.
    10.  
    11. Open the .\Master\config\mtxagent.ini file using any text editor.
    12.  
    13. Set the CertAuth and CertTrusted parameters in this mtxagent.ini file to the name of the certificate filed (without extensions). For example, if your certificate files are named "mycert.crt" and "mycert.key", these parameters in the INI should be set to "mycert"
    14.  
    15. Start the Client Management agent on the master server.
    16.  
    17. Follow the steps in the "Including the certificate in agent rollouts" section below to include your certificate for newly installed agents, as this certificate will be needed to allow agents to communicate with the master.
       Install certificate in existing environment (already has relays/clients)

    Please note that the steps below assume that your master server is already configured to use SSL connections with the built-in certificate. If your master server is not yet configured for SSL, please follow the steps in   this knowledge base 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.  
    3. 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.
    4.  
    5. 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.  
    3. Navigate to the directory where the master agent has been installed. This is typically \Program Files\BMC Software\Client Management\Master\.
    4.  
    5. Copy the .crt and .key file for your certificate into the .\Master\bin\certs\auth\ directory.
    6.  
    7. Copy the .crt file for your certificate into the .\Master\bin\certs\trusted\ directory.
    8.  
    9. Copy the .crt file for your 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.
    10.  
    11. Open the .\Master\config\mtxagent.ini file using any text editor.
    12.  
    13. 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 your 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.    
      3. 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 your certificate files are named "mycert.crt" and "mycert.key" , this parameter should be set to "CertTrusted=mycert,amp"
      4.   
    14.  
    15. 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.
    16.  
    17. Start the agent service on the master server.
    18.  
    19. 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.    
      3. Copy the .crt and .key file for your certificate into the .\auth\ directory.
      4.    
      5. Copy the .crt file for your certificate into the .\trusted\ directory.
      6.    
      7. 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.
      8.    
      9. On the next screen, enter a name for the package, and ensure the Installation Options and Add Files options are checked.
      10.    
      11. On the Installation Options page in the wizard, enter "./certs" (without the quotes) for the Destination Path. Leave the remaining options on this page at the default settings.
      12.    
      13. 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.
      14.    
      15. On the Publication page, select to publish the package to the master server, and click finish.
      16.    
      17. After completing the package creation wizard, you will be prompted to start a new wizard. Please select the option to "Create an Operational Rule" and click OK.
      18.    
      19. 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.
      20.    
      21. 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.      
        3. For the Authority Certificate parameter, enter the same value as the CertAuth parameter from the master server's mtxagent.ini (see step 8 above)
        4.      
        5. For the Trusted Authorities parameter, enter the same value as the CertTrusted parameter from the master server's mtxagent.ini
        6.      
        7. The User Certificate field should be left blank
        8.      
        9. the remaining options can be set as desired.
        10.     
      22.    
      23. Add the Restart Agent step to this rule as well. The rule should now contain 3 steps in the following order Install Package (this was added automatically for you), Agent Parameter Setup, and Restart Agent.
      24.   
    20.  
    21. Assign this operational rule to all client and relay devices.
    22.  
    23. Once all devices have executed the rule to install the certificate files, we will 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.    
      3. Enter a name for this new rule, and click OK.
      4.    
      5. From the rule created in step 11 above, copy the Agent Parameter Setup and Restart agent steps into the newly created rule
      6.    
      7. 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 your new certificate is "mycert.crt" please enter "mycert".
      8.    
      9. 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.
      10.   
    24.  
    25. Assign this rule to all devices, including the master server.
    26.  
    27. Once all devices have executed this rule, we will 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.    
      3. Enter a name for this new rule, and click OK.
      4.    
      5. From the rule created in step 13 above, copy the Agent Parameter Setup and Restart agent steps into the newly created rule
      6.    
      7. Double click the Agent Parameter Setup step, and for the Trusted Authorities parameter, ensure that your new certificate name is the only entry. For example, if your certificate file is named "mycert.crt", enter "mycert" for this parameter.
      8.   
    28.  
    29. Assign this rule to all devices, including the master server.
    30.  
    31. Follow the steps in the "Including the certificate in agent rollouts" section below to include your 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 clients to be able to communicate with the master server, they must use a certificate which the master agent trusts, so we must include the .crt and .key files in agent rollouts as described below:  
       
    1. Ensure that the .crt and .key files for your certificate are available on the master server. These files can be in any location on the master.
    2.  
    3. Start the Agent Rollout by clicking Wizard Wizards > Agent Rollout in the console.
    4.  
    5. 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 your desired configuration. The remainder of these instructions assume that these are the only options checked.
    6.  
    7. Fill in the fields on the General Parameters tab as desired
    8.  
    9. On the Security step in the wizard, ensure the Authority Certificate and Trusted Authorities fields show the name of your certificate. For example, if the filename for your certificate is "mycert.crt", these fields should read "mycert".
    10.  
    11. the Post-Install step in the wizard, click the Add button under the Files section
    12.  
    13. Browse for the .crt file for your certificate. When prompted for a destination path enter "./bin/certs/trusted" (without the quotes).
    14.  
    15. Browse for the .crt file for your certificate again. When prompted for a destination path enter "./bin/certs/auth" (without the quotes).
    16.  
    17. Browse for the .key file for your certificate. When prompted for a destination path enter "./bin/certs/auth" (without the quotes).
    18.  
    19. Proceed through the remainder of the rollout wizard as you otherwise would.
    If you would like to modify an existing rollout, rather than create a new one, you can add the certificate files as described above on the Files tab under the Post-Install node of the rollout. Also, please 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 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 your own certificate for the master, you 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 Java Web Start button to install the Java Web Start console
      2.    
      3. Depending on the browser you are using, you may need to double click the console.jnlp file downloaded from this page (some browsers will launch this automatically).
      4.    
      5. When the login window is displayed, click the Cancel button to close the console (you will need to complete the below steps to install the certificate before you will be able to login)
      6.   
    2.  
    3. Navigate to the %appdata%\Numara AMP\ directory (on a Windows 7 system, this will be equivalent to c:\users\%USERNAME%\AppData\Roaming\Numara AMP\). You should see a file here named ConsoleState.properties.
    4.  
    5. Create a folder named "certs", then create a folder named "trusted" inside the certs folder
    6.  
    7. 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 you can 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 login with the Client Management console after installing your own certificate for the master, you 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.    
      3. Extract the contents of the zip file downloaded above
      4.    
      5. From the directory where this zip file was extracted, run the appropriate setup batch file (depending on your language). For example, for English you would run the "setup_en.bat" file
      6.   
    2.  
    3. 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".
    4.  
    5. Create a folder named "certs", then create a folder named "trusted" inside the certs folder
    6.  
    7. Copy the .crt file into the \Program Files\BMC Software\Client Management\Console\certs\trusted\ directory
      

      

     


    Article Number:

    000010318


    Article Type:

    Solutions to a Product Problem



      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles