Configuring mutual authentication
To use mutual authentication, servers and Java Message Service (JMS) agents must exchange keys. You export a server key as a certificate and import it into the JMS agent keystore. Then, you reverse the process by exporting the agent key and importing it into the server keystore.
Before you begin
- Set the server.jms.mutualAuth property in the server's
installed.properties file (in the
server_install/conf/server directory) to
true
. - For each JMS agent, set the locked/agent.mutual_auth property in the
agent's installed.properties file (in the
agent_install\conf\agent directory) to
true
. - For each agent relay, set the agentrelay.jms_proxy.secure property in the
relay's agentrelay.properties file (in the
relay_install\conf directory) to
true
. - For each agent relay, set the agentrelay.jms_proxy.mutualAuth property in
the relay's agentrelay.properties file to
true
.
Additionally, ensure that the keytool utility, which is provided with the Java™ developer kit and is not part of HCL Launch, is available in the system path on each server, agent, and agent relay.
Mutual authentication is not needed with web agents, therefore is deprecated starting in HCL Launch version 7.0.0.
About this task
- If you enable mutual authentication and use self-signed certificates, you must exchange the keys between server and agent relay, agent relay and agent, or between server and agent.
- If you use mutual authentication and certificates signed by an internal CA, you must ensure that the root certificates of the certificate chains are trusted by the Java virtual machine of the receiver. You do not have to exchange individual keys.
- If you use mutual authentication and certificates signed that are by a well-known CA that is trusted by the Java virtual machine, you do not have to exchange keys or root certificates.
The advantage of using any form of signed certificates for mutual authentication is that you do not have to restart the server or agent relay every time you add the key for a new agent to the server or relay keystore. Any agent that supplies a certificate that is trusted by the server or agent relay that it connects to is allowed to communicate with the server or agent relay.
The keys for mutual authentication are stored in the following keystore files.
- server.keystore in the conf folder of each server
- agent.keystore in the conf folder of each JMS agen
- agentrelay.keystore in the conf/jms-relay folder of each agent relay
- ibm-ucd_agent (for JMS mutual authentication in JMS agents)
- ucd-agent-<id> (for end-to-end JMS encryption in JMS agents and for the web protocol in web agents)
In the following steps, you export the key from each system and import it into each component by using the keytool utility.
To configure mutual authentication for high-availability environments, swap all JMS agents, or agent relay, certificates with each server. Ensure that all JMS agents and agent relays have certificates from all servers, and all servers have certificates from all JMS 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 JMS agent or agent relay that connects directly to
the server:
-
Copy the certificate from each JMS agent or agent relay that connects directly to the server
and import that certificate into the server keystore:
- Optional:
For each local JMS agent or agent relay, set the key alias to the same value that you used on
the server.
From the JMS agent's conf directory or the agent relay's jms-relay directory, run this command:
The default JMS agent alias iskeytool -changealias -destalias uniqueAlias -alias defaultAlias -keystore agent.keystore -storepass changeit
ibm-ucd_agent
, and the default agent relay alias isagentrelay
. -
If you use agent relays, use the established methods to connect remote JMS agents to
them.
Each remote JMS agent must import the certificate for the relay, and the relay must import the certificate from each remote JMS agent in addition to the certificate from the server.
- Restart the server, JMS agents, and agent relays.
What to do next
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