Changing security certificates in App Visibility components

By default, App Visibility components use pregenerated, self-signed certificates for authentication between the server components, agents, and the Presentation Server. You can replace the pregenerated certificates with custom certificates.

This topic contains the following sections: 

Certificates for Synthetic TEA Agents

To implement security certificates on Synthetic TEA Agents see Changing-security-certificates-on-Synthetic-TEA-Agents and Replacing security certificates in BMC PATROL for Application Management 10.7.

App Visibility certificate overview

The following diagram shows the components of the App Visibility environment, and the properties files that manage the keystore file names and passwords on each component. The arrows represent the flow of data between the components.

Related topics

Implementing private certificates in TrueSight Operations ManagementSecurity planning for Presentation ServerImporting a keystore file or replacing the certificate for the App Visibility proxy

Setting-up-and-managing-the-App-Visibility-components-and-databases

App Visibility components and the properties files that manage certificates

avm_security_files.png

To use your own security certificate, put a certificate on each component, and then edit the properties files on each component to use the new certificates and password.

Notes

  • After you change or import a certificate, you must restart the component.

  • This topic does not include importing a KeyStore file or replacing the certificate for CA-signed certificates on the App Visibility proxy, which enables secure data collection from the end users of your web applications.

Before you begin

  • Install and   configure App Visibility components.

  • Prepare security files for the following components.

    • For App Visibility server components and App Visibility agents for Java, and for the Presentation server, prepare the following files. For details about creating the files, see the Java Keytool documentation on the Oracle website.

      • keystoreFileName.jks, where keystoreFileName is your custom keystore file name
      • truststoreFileName.jks, where truststoreFileName is your custom truststore file name

      Tip

      Create one file of each file type and use copies of the same files for all components: portal, collector, proxy, and agents.

    • For App Visibility agents for .NET, prepare the following files. These are the same certificates, but in a different format:
      • keystoreFileName.p12, where  keystoreFileName is your custom keystore file name, and the file is in X.509/PKCS#12 format

      • truststoreFileName.cer, where truststoreFileName is your custom certificate file name, and the file is in X.509/PKCS#7 format

        Note

        The truststore file for the agent for .NET must have the .cer file extension.

  • (For multitenancy) In a multitenancy environment, you can prepare one set of keystore and truststore files for each tenant. If you do not specify separate files for a tenant, the designated default certificate will be used.
  • Prepare an encrypted password (instructions near the end of this topic) for each security file. This is the same password that you used to create the keystore.
Warning
  • Communication is interrupted while replacing certificates and data collection stops, or is incomplete, until the process is complete.
  • Changes to security certificates on the agents require you to restart the application servers or IIS servers.

To replace security files for App Visibility server components

For each App Visibility server component, perform the following procedure.

  1. Place your keystore and truststore files on each component computer.
  2. Open the specified properties file (see the following table).
  3. Replace the default path and file name of the keystore and truststore with the path and file name of your files.
  4. Replace the default password with your encrypted password value.
    The system uses the password only for the keystore.
  5. Save the file and restart the service.

The following table lists the file paths and file names of the properties files for the App Visibility server components. The keystore and truststore files are located in the installationDirectory/component/security directory (default installationDirectory is C:\Program Files\BMC Software\App Visibility for Windows and /opt/bmc/App_Visibility for Linux). 

In the properties files, you must provide a relative path to the keystore and truststore files in the security directory.

App Visibility server security files and parameters

Properties file

Parameter*

portalInstallationDirectory/portal/properties/portal.properties

key.store.file.path=relativePath/keystoreFileName.jks
trust.store.file.path=relativePath/truststoreFileName.jks
key.store.password.enc=encryptedPassword
key.store.alias=keystoreAlias

collectorInstallationDirectory/collector/properties/collector.properties

key.store.file.path=relativePath/keystoreFileName.jks
trust.store.file.path=relativePath/truststoreFileName.jks
key.store.password.enc=encryptedPassword
key.store.alias=keystoreAlias

proxyInstallationDirectory/apm-proxy/properties/apm-proxy.properties

key.store.file.path=relativePath/keystoreFileName.jks
trust.store.file.path=relativePath/truststoreFileName.jks
key.store.password.enc=encryptedPassword
key.store.alias=keystoreAlias

* Use a forward slash (/) for file paths, even on Windows systems.

Tip

Use the same file with the same values for all the components: keystoreFileName.jks, truststoreFileName.jks, encryptedPassword , keystoreAlias .

To replace security files for App Visibility agents for Java

For each App Visibility agent for Java, perform the following procedure.

  1. Place your keystore and truststore files in the agentInstallationDirectory /ADOPsInstall/properties directory on each computer where the agent for Java is installed.
  2. Open the portal.connection.properties file, located in the agentInstallationDirectory /ADOPsInstall/properties directory. 

  3. Replace the default file name of the keystore and truststore with the names of your files:

    key.store.file.name=keystoreFileName.jks
    trust.store.file.name=truststoreFileName.jks

  4. Replace the default password with your encrypted password value:

    key.store.password.enc=encryptedPassword

    The system uses the password only for the keystore.

  5. Save the file and restart the application server.

To replace security files for App Visibility agents for .NET

For each App Visibility agent for .NET, perform the following procedure.

  1. Place your keystore and truststore files in the  agentInstallationDirectory/properties directory on each computer where the agent for .NET is installed.
  2. Open the agents.properties file, located in the agentInstallationDirectory/properties directory.

  3. Replace the default path and file name of the keystore and truststore with the path and file name of your files:

    key.store.file.name=keystoreFileName.p12
    trust.store.file.name=truststoreFileName.cer

  4. Replace the default password with your encrypted password value.

    key.store.password.enc=encryptedPassword

    The system uses the password only for the keystore.

  5. Save the file and restart IIS.

To replace security files for communication with the Presentation Server (on premises)

Certificate details for internal communication between the Presentation Server and the App Visibility portal are managed by the App Visibility certificates file, appVisCertificates.xml, which contains default certificate information and is located on the Presentation Server.

You can use your own default certificate and update the values of the default-certificate element in the appVisCertificates.xml file. In an environment with multiple tenants, you can add a tenant-certificate element for each tenant. If you do not define a tenant-certificate for one or more tenants, those tenants use the default-certificate values, instead.

  1. Place your keystore file and (optional) truststore file (or multiple files for multiple tenants) on the Presentation Server computer.

    Best practice

    To preserve certificates after you upgrade the Presentation Server, place your file or files in one of the following directories on the Presentation Server:

    • In the TSPSinstallationdirectory/conf/secure/appVisSecure directory, which is reserved for custom App Visibility certificates. When you update the file path in the certificate configuration file (as described in the following steps) you can use a relative path.
    • In any directory that is not under the Presentation Server installation directory. When you update the file path in the certificate configuration file (as described in the following steps), BMC recommends using the full file path.
  2. Open the appVisCertificates.xml file, located in the tspsInstallationDirectory/conf directory.
  3. Update the following elements, as required:*

    • To replace the default certificate, replace the default path and file name of the keystore and (optional) the truststore, and the password with the values for your keystore file:

      <default-certificate path="conf/secure/appVisSecure/keystoreFileName.jks" password="encryptedPassword" truststorePath="conf/secure/appVisSecure/truststoreFileName.jks"/>

      Replace the following values:

      • keystoreFileName
      • encryptedPassword
      • truststoreFileName

    • To add a certificate for one or more tenants, add the following element for each tenant, and use your values for the tenant name, path and file name of the keystore file and (optional) truststore files, and the encrypted password.

      <tenant-certificate tenant="tenant1Name" path="conf/secure/appVisSecure/keystoreFileName.jks" password="encryptedPassword" truststorePath="conf/secure/appVisSecure/truststoreFileName.jks"/><tenant-certificate tenant="tenant2Name" path="conf/secure/appVisSecure/keystoreFileName.jks" password="encryptedPassword" truststorePath="conf/secure/appVisSecure/truststoreFileName.jks"/>

      Replace the following values:

      • tenant1Name, tenant2Name
      • keystoreFileName
      • encryptedPassword
      • truststoreFileName

       

  4. Save the file and restart the Presentation Server service by running the following command:
    Failed to execute the [excerpt-include] macro. Cause: [Error number 2 in 0: No wiki with id [confluencePage:page] could be found]. Click on this message for details.

* Use a forward slash (/) for file paths, even on Windows systems.

Encrypting a new keystore password for the App Visibility server properties files

Use an encrypted password so that the plain text password is not displayed in your App Visibility server properties files. After you encrypt the new password, copy the encrypted password to the relevant properties file.

To encrypt a new keystore password

Encrypt the password with the provided script, located on the portal or collector computer.

Windows

  1. On the App Visibility portal or collector computer, open a command prompt, and run the following command:

    portalInstallationDirectory/portal/bin/passwordEncrypt.bat NewPassword 
    or
    collectorInstallationDirectory/collector/bin/passwordEncrypt.bat NewPassword  

    NewPassword is the password you want to encrypt.
    A message is displayed while the password is encrypted and upon completion, the encrypted password is displayed.

  2. Copy the encrypted password and paste it in the relevant properties file.

Linux

  1. On the App Visibility portal or collector computer, change to the required directory:
    • portalInstallationDirectory/portal/bin
    • collectorInstallationDirectory/collector/bin

  2. Run the following command:

    ./passwordEncrypt.sh NewPassword  

    NewPassword is the password you want to encrypt.
    A message is displayed while the password is encrypted and upon completion, the encrypted password is displayed.

  3. Copy the encrypted password and paste it in the relevant properties file.