Enable SSL Communication - WSO2 Message Broker

When come to enterprise, security is a big concern.  When communicating with a Message Broker your messages are communicated with the broker along the network. Thus it is needed to encrypt the  communicated  messages in TCP layer for enhanced security.

With WSO2 Message Broker 2.2.0 and onwards (we have already distributed a patch with this capability to our enterprise partners) we will support "Communicating With SSL". This post explains how this new feature can be enabled and configured to suit your environment.

Server Side Configurations

WSO2 Message Broker can enable non-ssl port (default - 5672), and ssl-port (default- 5671) at the same time or strictly SSL only. If some of your clients are within the secured network they can communicate with non-ssl and other clients which are outside the secured network can communicate with the broker using ssl. For such a use case, fist option can be used. 

To configure "strictly SSL" or not,  use following configuration at Broker side. You need to edit
<MB_HOME>/repository/conf/advanced/qpid­config.xml file. 

<!­­ To enable SSL edit the keystorePath and keystorePassword
and set enabled to true.
To disasble Non­SSL port set sslOnly to true ­­>

  • <enabled> : By default SSL is enabled in WSO2 MB hence this value is set to 'true'. If you set this to 'false' broker will be only starting in non­ssl port.
  • <sslOnly> : States whether to allow/not allow making connections to broker via secured port only. If set to 'true' non­ssl port is disabled.
  • <keystorePath> : Add the path to the keystore here.
  • <keystorePassword> : Specify the password to access the keystore.
Generally for Carbon servers we put keystore file at <MB_HOME>/repository/resources/security folder. 

Configuring JMS Clients to use SSL 

SSL parameters are configured and sent to the broker as broker options in the
TCPConnectionURL defined by the client. It is needed set 'ssl=true' in the url and specify the
keystore and client trust store paths and passwords. Use the below connection url format to
pass the SSL parameters.

String connectionURL =

Note the setting 'ssl_cert_alias' property is not mandatory and can be used as an optional way of specifying which certificate the broker should use if the truststore contains multiple entries.
An example connection url which uses default keystores and trust stores in WSO2 carbon
products is as follows.

String conUrl =

Failover Configuration to Servers with Different Private Keys

Say you have configured a WSO2 Message Broker cluster and you need to configure fail-over. If those broker nodes have different certs in place, when configuring fail-over connection url at client side, you can individually specify a client trust store and a key store for each broker in broker list. Or else, you can import certs of all brokers in the cluster to a single trust store with different cert alias and differentiate the cert to use when failing over by the alias. 

Configure WSO2 ESB to Communicate with WSO2 MB with SSL

simply, what you need to do is configure above ssl-url at <ESB_HOME>/repository/conf/jndi.properties file.

Hasitha Hiranya

1 comment:

  1. Hi Hasitha,

    Great article and very helpful. We have successfully configured JMS SSL connectivity between our WSO2 ESB our WSO2 MB using the above method. However, we are attempting to use the standalone client from a non-WSO2 Spark server using the same amqp connection string and we are seeing the error " javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection" Are you aware of any good documentation around configuring the standalone client to use SSL in this manor?