Securing Health Center

If you are monitoring an application on a remote machine, you might want to secure the connection between the Health Center client on your machine, and the monitoring agent on the remote machine. The security technology varies depending on the connection type, but can include a simple user name and password, MBean authentication, or Secure Sockets Layer (SSL). If you are using IBM® Bluemix®, no security options are available.

About this task

When you connect the Health Center client to the agent, to monitor your application, you can choose from the following security options. The options that are available depend on whether you choose a JMX or MQTT connection. If your application is not a Java™ application, you must use an MQTT connection.

No security

The connection is unencrypted, and no user name or password is required.

MBean authentication (JMX connections only)

This method uses JMX technology. Data that passes between the client and the agent is unencrypted, but a user name and password are required for the client to connect to the agent. The user name and password are stored in an authentication file that you create. You also create an authorization file, to specify the access for that user name. You can add multiple user names to each file. You then use Health Center properties to specify the location of these files, so that the agent can find them. For example:

java -Xhealthcenter -Dcom.ibm.java.diagnostics.healthcenter.agent.authentication.file=/home/user/authentication.txt -Dcom.ibm.java.diagnostics.healthcenter.agent.authorization.file=/home/user/authorization.txt HelloWorld

Simple authentication (MQTT connections only)

This method uses the user name and password of your MQTT broker. To use this method you must set a user name and password for your broker, then specify that user name and password in Health Center. In addition to specifying the user name and password in the client, you must use the Health Center properties file to set the user name and password for the agent.

SSL connection (JMX connections only)

No user name or password is required for the client to connect to the agent, but the SSL protocol is used to encrypt the data that passes across the connection. To use this method you must create a keystore and a public/private key pair for both the client and the agent, then swap the public key certificates. The client and the agent must be able to find and access their respective keystores. For the client, you set the location and password for the keystore in a dialog box when you connect to the agent. For the agent, you use Health Center properties to set the location and password.

SSL connection and MBean authentication (JMX connections only)

You can use MBean authentication over an SSL connection. You must create the required files for each security method.

Procedure

Decide which security method you want to use.
Optional: If you want to use MBean authentication (JMX connections only), complete the following steps:
1. Create a file to store the MBean authentication user name and password.
  You can use any values for the file name, extension, and location, as long as the file is accessible by the Health Center agent. For example, the file might need to be on the same machine as the agent.
  Use only alphanumeric characters for the user name and password; do not use spaces or symbols. Configure the permissions on the file so that only authorized users can see the contents.
  For example, create a file called authentication.txt, which has the following contents:
```
myuser mypassw0rd
anotheruser theirpassw0rd
```
2. Create an authorization file to specify read and write access for the user name that you specified earlier.
  This file must also be accessible by the Health Center agent.
  Specify read and write access by adding readwrite after the user name. For example, create a file called authorization.txt, which has the following contents:
```
myuser readwrite
anotheruser readwrite
```
3. Use the following Health Center properties to specify the location of the files, so that the agent can find them.
  Authentication file:
```
com.ibm.java.diagnostics.healthcenter.agent.authentication.file
```
  Authorization file:
```
com.ibm.java.diagnostics.healthcenter.agent.authorization.file
```
  You specify these properties either on the command line, when you start the application or attach the Health Center agent to a running application, or in the Health Center system properties file. For more information, see Configuring the monitoring agent.
Optional: If you want to use an SSL connection (JMX connections only), complete the following steps:
1. On the machine that is running the Health Center agent, create a keystore and key pair for the agent.
  You can use the keytool utility in IBM SDK and Runtime Environment, Java Technology Edition to create the keystore and key pair.
  For example, the following command creates these objects:
  - A keystore called HCAgentKeystore, in the current directory
  - A key pair that is generated with the RSA algorithm. The key is 2048 bits long, and is valid for 200 days. The key pair has an alias of HCAgentKey.
```
keytool -keystore HCAgentKeystore -genkeypair -keyalg RSA -keysize 2048 -validity 200 -alias HCAgentKey
```
  Note: You are prompted for the keystore password, your name and location, and the key (certificate) password. If you do not supply a value for the certificate password, the certificate password is set to the same password as that used for the keystore
  For more information about the keytool utility and the available command options, see the keytool user guide in the documentation for your version of IBM SDK and Runtime Environment Java Technology Edition.
2. Export the public key certificate from the key pair.
  For example, the following command exports the public certificate for the HCAgentKeystore key pair to the HCAgentKey.pub file:
```
keytool -keystore HCAgentKeystore -exportcert -alias HCAgentKey -rfc -file HCAgentKey.pub
```
  The -rfc parameter specifies that the file is generated in the printable encoding format.
3. On the machine that is running the Health Center client, follow the same steps to create a keystore and a key pair for the client, then export the public key certificate.
  For example:
```
keytool -keystore HCClientKeystore -genkeypair -keyalg RSA -keysize 2048 -validity 200 -alias HCClientKey

keytool -keystore HCClientKeystore -exportcert -alias HCClientKey -rfc -file HCClientKey.pub
```
4. Swap the public key certificates, by importing the agent public key certificate into the client keystore, then importing the client public key certificate into the agent keystore.
  For example, on the machine that is running the agent:
```
keytool -keystore HCAgentKeystore -importcert -file HCClientKey.pub
```
  On the machine that is running the client:
```
keytool -keystore HCClientKeystore -importcert -file HCAgentKey.pub
```
5. For the Health Center agent, use the following Health Center properties to specify the location and password of the agent keystore, so that the agent can find the required keys.
  Keystore location:
```
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStore
```
  Keystore password:
```
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStorePassword
```
  Keystore certificate password:
```
com.ibm.java.diagnostics.healthcenter.agent.ssl.keyStoreCertificatePassword
```
  You specify these properties either on the command line, when you start the application or attach the Health Center agent to a running application (Java applications only), or in the Health Center system properties file. For more information, see Configuring the monitoring agent.
  For the Health Center client, you specify the location and password of the client keystore when you connect to the agent, see What to do next.
If you want to use simple authentication (MQTT connections only), complete the following steps:
1. Set a user name and password for your MQTT broker.
  Refer to the documentation for your MQTT broker for information on how to set these credentials.
2. Set the com.ibm.diagnostics.healthcenter.mqtt.broker.user and com.ibm.diagnostics.healthcenter.mqtt.broker.pass properties in the monitoring agent properties file to match the broker user name and password.
  For more information about configuration properties, see Health Center configuration properties.
  Note: The credentials are stored in the Health Center properties file as plain text.

Results

You created the files that are required to secure the Health Center connection.

What to do next

If you are concerned about a denial-of-service attack, set the com.ibm.diagnostics.healthcenter.readonly property in the monitoring agent properties file to on, so that the agent ignores request from the client for actions that might disrupt the monitored application. For more information, see Health Center configuration properties
Start the Health Center client and connect to the agent, specifying the security option that you chose in step 1, and the required credentials. For example, if you chose to use SSL you must specify the location and password of the client keystore, and the keystore certificate password. For more information, see Connecting an application to the Health Center client.