Configuring mutual authentication

To use mutual authentication, servers and agents must exchange keys. You export a server key as a certificate and import it into the agent keystore. Then, you reverse the process by exporting the agent key and importing it into the server keystore.

Before you begin

Before you exchange keys, ensure that the following properties are set:

The server.jms.mutualAuth property in the server's installed.properties file (in the server_install/conf/server directory) is set to true.
For each agent, the locked/agent.mutual_auth property in the agent's installed.properties file (in the agent_install\conf\agent directory) is set to true.
For each agent relay, the agentrelay.jms_proxy.secure property in the relay's agentrelay.properties file (in the relay_install\conf directory) is set to true.
For each agent relay, the agentrelay.jms_proxy.mutualAuth property in the relay's agentrelay.properties file is set to true.

Additionally, ensure that the keytool utility, which is provided with the Java™ developer kit and is not part of IBM® UrbanCode™ Deploy, is available in the system path on each server, agent, and agent relay.

About this task

Each server, agent, and agent relay contains a key that identifies that system. Mutual authentication ensures the identity of each of those systems by exchanging these keys with each other. The keys are stored in the file encryption.keystore in the conf folder of each server, agent, and agent relay. In the following steps, you export the key from each system and import it into each other system using the keytool utility.

To configure mutual authentication for high-availability environments, swap all agent, or agent relay, certificates with each server. Ensure that all agents and agent relays have certificates from all servers, and all servers have certificates from all agents and agent relays. Importantly, ensure that each server uses the same certificate. For this purpose, load balancers can be ignored.

Procedure

Copy the certificate from the server to each agent or agent relay that connects directly to the server:
1. On the server, open a command-line window and go to the folder that contains the file server.keystore. By default, this folder is at the location app_data/conf, where app_data is the application data folder that you set at installation. The default application data folder is /opt/ibm-ucd/server/appdata on Linux and C:\Program Files\ibm-ucd\server\appdata on Windows. In the case of a high-availability cluster, the application data folder is usually on a shared remote directory.
2. Export the server key by running the following command:
```
keytool -exportcert -keystore server.keystore -storepass changeit -alias server -file server.crt
```
  If the certificate was exported, you see this message: Certificate stored in file server.crt.
3. Copy the exported key file server.crt to each agent installation conf directory or the agent relay installation conf/jms-relay directory.
4. Import the server certificate into the agent or agent relay keystore by running the following command from within the agent's conf directory or the agent relay's jms-relay directory:
```
keytool -importcert -keystore keystoreFile -storepass changeit -alias server -file server.crt -keypass changeit -noprompt
```
  For keystoreFile, use agent.keystore for agents and agentrelay.keystore for agent relays. If the certificate was imported, you see this message: Certificate was added to keystore. The agent.keystore and encryption.keystore files are not generated until the first time the agent is run.
5. Repeat the process for each agent and agent relay that connects directly to the server.
  Note: Agents that communicate with the server through agent relays do not have to swap certificates with the server. Only the agent relay that connects to the server must swap certificates with the server. However, you must swap certificates between the agent relay and each remote agent.
Copy the certificate from each agent or agent relay that connects directly to the server and import that certificate into the server keystore:
1. On the system that hosts the agent or agent relay, open a command-line window and go to the folder that contains the file agent.keystore or agentrelay.keystore.
2. Export the certificate by running the following command:
```
keytool -exportcert -keystore keystoreFile -storepass changeit 
-alias ibm-ucd_agent -file agentName.crt
```
  For keystoreFile, use agent.keystore for agents and agentrelay.keystore for agent relays. The default agent alias is ibm-ucd_agent. For agentName, specify a unique string identifier for the agent or agent relay. If the certificate was exported, you see this message: Certificate stored in file agentName.crt.
3. Copy the exported key file to the server app_data/conf folder, where app_data is the application data folder.
4. Import the agent or agent relay certificate into the server keystore by running the following command:
```
keytool -importcert -keystore server.keystore -storepass changeit 
-alias uniqueAlias -file agentName.crt -keypass changeit -noprompt
```
  For uniqueAlias, use a unique key alias that identifies the agent. If the certificate was imported, you see this message: Certificate was added to keystore. The agent.keystore and encryption.keystore files are not generated until the first time the agent is run.
5. Repeat the process for each agent and agent relay that connects directly to the server.
  Note: Agents that communicate with the server through agent relays do not have to swap certificates with the server. Only the agent relay that connects to the server must swap certificates with the server. However, you must swap certificates between the agent relay and each remote agent.
Optional: For each local agent or agent relay, set the key alias to the same value that you used on the server. From the agent's conf directory or the agent relay's jms-relay directory, run the following command:
```
keytool -changealias -destalias uniqueAlias -alias defaultAlias -keystore agent.keystore -storepass changeit
```
The default agent alias is ibm-ucd_agent, and the default agent relay alias is agentrelay.
If you use agent relays, use the established methods to connect remote agents to them. Each remote agent must import the certificate for the relay, and the relay must import the certificate from each remote agent in addition to the certificate from the server.
Restart the server, agents, and agent relays.

What to do next

Ensure that the agents and agent relays can connect to the server.

You can also list the certificates that are loaded into a keystore by running the following command from within the conf directory:

keytool -list -keystore keystoreFile -storepass changeit

For more information about exchanging keys among servers, see Sharing secured properties among servers.

To revoke the keys that the agent uses to connect to the server, follow these steps:

Log in as a user with the "Manage Security" permission.
Open the agent and then click Configuration > Agent Security. This tab is only shown if you have the "Manage Security" permission and if the agent uses mutual authentication to connect to the server.
To revoke the API key that the agent uses, click Forget API Key. Clicking this button is equivalent to removing the API key on the Settings > API Keys and Certificates > API Keys and removing the key there.
To revoke the JMS certificate that the agent uses to connect to the server, click Revoke API Key.

Feedback