Securing JMS connections to WebSphere Enterprise Service Bus V6.1 or V6.2

Security is an integral part of SOA, and since WebSphere ESB is at the heart of many SOA solutions, the security of a WebSphere ESB server and its transports is vital to the enterprise systems that use it. Messaging, such as the JMS implementation provided by WebSphere ESB, is particularly important for business applications because of its reliability, performance, and asynchronous nature. This article shows you how to implement security with an example using WebSphere ESB V6.1 and a J2EE client container application communicating via JMS messaging.


Dave Screen (, Software Engineer, IBM

Dave Screen is a Software Engineer at the IBM Hursley Software Lab in the UK. His job involves helping customers and IBM colleagues use WebSphere ESB. His experience includes WebSphere, security, transactions, Java runtimes, and Eclipse. You can contact Dave at

18 February 2009

Also available in


The article is for SOA developers, integration specialists, and system administrators using IBM® WebSphere® Enterprise Service Bus V6.1 or V6.2 (hereafter called WebSphere ESB). Everything in this article also applies to WebSphere Process Server. The underlying messaging infrastructure is provided by the Service Integration Bus (SIBus) that is part of WebSphere Application Server. Therefore most of the steps also apply to securing other types of JMS applications running on application server based products. You should have some experience using WebSphere Application Server or products built upon it, such as WebSphere ESB. WebSphere Integration Developer (hereafter called Integration Developer) can also be used to deploy applications and control the server. The sample code was developed using Integration Developer V6.1.0.1, and it will run on either WebSphere ESB V6.1 or later, or on WebSphere Process Server V6.1 or later. You can download the sample code at the bottom of the article.


This article will first describe WebSphere ESB security and the article scenario, then show you how to secure JMS connections between client and server.

Security overview

There are several aspects of security configuration in WebSphere ESB:

  • Administrative security
  • Transport security
  • Bus security

Administrative ("admin") security acts like a master on/off switch. When switched on (enabled), only authenticated and authorized users can administer the system. It has other security related side-effects, such as certain ports become restricted to SSL, for example logging into the Integrated Solutions Console (ISC or "admin console"). Certain features function only with administrative security, such as user registries (for example, users can be authenticated via LDAP) and bus security – described below.

Transport security involves securing the channels in and out of the server. These include HTTP, JMS, and RMI-IIOP. This can involve setting up SSL configurations and applying them to each open port. SSL can provide confidentiality (by encryption) and authentication (by configuring to only allow trusted certificates).

WebSphere ESB defines buses on the SIBus infrastructure that are used by applications such as mediation modules. There are many security features available, such as:

  • Authentication – Applications/users must provide a username and password to use the bus
  • Authorization – Users can access resources based on the roles they are assigned. For example a user needs the bus connector role to connect to a bus
  • Permitted transport chains – A bus can be configured to only allow access using secure transports

For more information, see Resources at the bottom of the article.

Improvements in V6.1 security

One of the major changes in V6.1 is that by default, the profile creation wizard creates secure profiles, which involves:

  • Admin security enabled with a primary server user ID defined
  • File-based user registry activated and containing the supplied user ID
  • Application security enabled
  • Usernames and passwords provided for J2C authentication aliases such as SCA_Auth_Alias (used by SCA applications to connect to the bus)
  • Bus security enabled, including permitting only SSL-protected transports and putting the server user ID into the bus connector role

In V6.0 all of the security features were off by default. It had the less granular concept of global security that combined admin and application security, and fewer SIBus security features. V6.1 has many other improvements, notably in key and certificate management. For more information, see Resources at the bottom of the article.

Weather service

To help you understand the concepts and instructions, the article uses the following scenario:

Figure 1. JMS client and WebSphere ESB server
Figure 1

You can download the scenario including the Project Interchange file (PIF) at the bottom of the article. The scenario involves the following components:

  • UKWeatherClient -- JMS client that sends messages to WebSphere ESB.
  • JMSWeatherForecast -- WebSphere ESB Module that provides a JMS interface to the client and connects to the internal SCA binding of WeatherMediation.
  • WeatherMediation -- WebSphere ESB Mediation Module that routes based on a location parameter to an appropriate weather service. In this case the only service is UKWeatherService.
  • UKWeatherService -- >WebSphere ESB Module that provides a simple Java implementation of the weather service.

Aside from security, the sample has been split into three modules as a design decision, to enable reuse with little or no modification to the existing modules. For example, a SOAPHTTPWeatherForecast module can be created containing a SOAP/HTTP export and wired to the WeatherMediation module to provide a Web Services interface. Another example is that a new module could be created to replace UKWeatherService and only the inter-module wiring of WeatherMediation would need to change. This change could be made at either development time in Integration Developer or run time in the ISC. The disadvantage is that as the number of modules increases, so does overhead in deployment, execution, and maintenance.

The interface exposed by JMSWeatherForecast accepts two parameters, location and day, and returns a String result named weatherCondition. Sample input values are UK and Tuesday respectively. Sample output for these inputs is Sunny. All other days return the result Cloudy.

Running the scenario without security

The steps below start by running the sample without security and then demonstrate incrementally increasing the security level using features of WebSphere ESB. This technique shows that after applying each security feature, the client’s invocation of the service will fail, and you can then modify the configuration so that it runs successfully again.

Creating a server profile

As discussed above, by default, server profiles in V6.1 have security enabled. For the purposes of this article, start with a server without security configured, by creating a new server profile:

  1. Launch the Profile Management Tool:
    • For a standalone server installation, it is at <ESB>\bin\ProfileManagement\pmt.bat, where <ESB> is the installation directory.
    • On Windows it is also available on the Start Menu.
    • If you are using the Integration Developer Unit Test Environment (UTE), launch the tool using <WID>\runtimes\bi_v61\bin\ProfileManagement\pmt.bat, where <WID> is the installation directory of Integration Developer.
  2. Click Create to start the wizard.
  3. On the Environment Selection page, click WebSphere Enterprise Service Bus profile.
  4. Follow the defaults (unless you want to change ports or choose a particular name), but uncheck the Enableadministrative security checkbox.
  5. Once the profile is created, add it to Integration Developer using the Servers view: Select Window => Show View => Other. Right-click and select New => Server. The server type is WebSphere ESB V6.1 Server and your new profile should be available on the next page:
    Figure 2. Adding newly created unsecure server profile to Integration Developer
    Figure 2

Installing the applications

  1. Install the three service applications (JMSWeatherForecastApp, UKWeatherServiceApp, and WeatherMediationApp) on the server. You can use the supplied EAR files in the ISC (or on the command line using wsadmin if you wish), where the default URL is http://localhost:9060/ibm/console, though ports can vary depending on your profile.
  2. Use Applications => Install New Application for each EAR file and accept the default installation options:
    Figure 3. Installing the application modules using the Integrated Solutions Console
    Figure 3
  3. Alternatively, for example when using the UTE, you can import the applications into Integration Developer using the supplied PIF and then publishing them using Add and Remove Projects in the Servers view of Integration Developer. This is not the recommended option for this article, because further configuration will be applied in the ISC after installation.
  4. If you use Add/Remove instead of the ISC to install the applications, then you need to set some options related to publishing in Integration Developer. Open the server configuration using the Servers view by double clicking on the server definition. Select Never publish automatically and Run server with resources on Server:
    Figure 4. Server configuration in Integration Developer
    Figure 4

The following steps will configure the provider endpoints for the JMS export. This is not necessary if the server is using the default SIBus communications port 7276 and the client is local. The port was chosen during profile creation and is visible in the ISC at Servers => Application servers => server1 => Ports => SIB_ENDPOINT_ADDRESS. If not correctly configured, a message like this will appear when you run the client later:

CWSIC1001E: A client attempted to connect with a remote messaging engine 
(localhost:7276 - BootstrapBasicMessaging) but the connection cannot be completed.

The provider endpoints information is used by the bootstrap server to identify the port of the messaging engine to be used for messaging communications.

  1. Open the Resources => JMS => Connection factories > JMSWeatherForecast.JMSWeatherForecastExport_CF panel.
  2. Set the Provider endpoints value to server_hostname:sib_endpoint_address_port:
    Figure 5. Example provider endpoints for connection factory
    Figure 5
  3. Click OK and then Save to save changes to the master configuration.
  4. Restart the server.

Running the client

You can launch the client on the command line using launchclient, or you can import the PIF into Integration Developer and launch it as a WebSphere V6.1 Application Client.

One improved feature in V6.1 is that when each profile is created, a self-signed personal certificate is generated and added to the NodeDefaultKeyStore key store used by the default SSL configuration. This is an improvement over V6.0 where all profiles across all installations had identical dummy certificates.

Later, we will use the client authentication feature of SSL to only allow connections from clients that are trusted by the server. To demonstrate this, it is useful to have a client profile that is separate to the server profile. This can be achieved by using a different installation (on the same or another machine), or by using another profile for the client (each profile has a unique key/certificate).

Create a new profile for the client without security configured using the Profile Management Tool described above. This profile will not need to be used as a server and can be created as either a custom or server profile. Run the application client EAR with the following command:

<install>\bin\launchclient –profileName <clientProfileName> <ClientEAR>
-cf JMSWeatherForecast/JMSWeatherForecastExport_CF
-request JMSWeatherForecast/JMSWeatherForecastExport_RECEIVE_D
-response JMSWeatherForecast/JMSWeatherForecastExport_SEND_D
-day Tuesday -location UK


  • <install> -- Install directory of your server. If using the UTE, this could be something like D:\WID61\runtimes\bi_v61.
  • <clientProfileName> -- Name of client profile created in step 1.
  • <ClientEAR> -- Path to UKWeatherClient.ear that is inside the zip available to download from this page.
  • <serverhost> -- Hostname of server
  • <serverbootstrapport> -- Bootstrap port for JNDI service on the server (default is 2809). To see it, select Application servers => server1 => Ports => BOOTSTRAP_ADDRESS in the ISC. This is the profile you created above in the section Creating a server profile.

Sample output:

D:\Workspaces\SecurityWeather>D:\WID61\runtimes\bi_v61\bin\launchClient -profileName NoSec
UKWeatherClient.ear -CCproviderURL=iiop://shaft:2813 -cf 
	JMSWeatherForecast/JMSWeatherForecastExport_CF -request
JMSWeatherForecast/JMSWeatherForecastExport_RECEIVE_D -response 
	JMSWeatherForecast/JMSWeatherForecastExport_SEND_D -day Tuesday -location UK
. . .
WSCL0014I: Invoking the Application Client class Main
JMSProxy : CF=JMSWeatherForecast/JMSWeatherForecastExport_CF
JMSProxy : RequestQ=JMSWeatherForecast/JMSWeatherForecastExport_RECEIVE_D
JMSProxy : ResponseQ=JMSWeatherForecast/JMSWeatherForecastExport_SEND_D
JMSProxy : Sending JMS message ...
JMSProxy : Waiting for response message ...
WeatherClient : Response : Success : Sunny

The client has used the bootstrap host and port to connect to the server and look up the connection factory using JNDI. This was then used to connect to a messaging engine and put a message on the SIBus. On the server, the JMS export of JMSWeatherForecast then picks up this message and invokes the WeatherMediation mediation flow. After the flow completes, the response message is retrieved by the client. The last line of output above indicates that a response message was successfully received by the client. For more information on buses and messaging engines, see Resources at the bottom of the article.

This process happened without any authorization and all data was sent unencrypted.

Configuring administrative security

In this section, administrative security will be enabled for the server profile. This will ensure that the client must supply credentials (username/password) in order to connect to the JNDI service. SIBus security will be configured in a later section.

Enabling WebSphere ESB server admin security

  1. We will configure the default file-based user registry, which holds user identities in an XML file inside the profile directory, with a new user identity. This username and password pair will be used as the primary administrative user on the server.
  2. In the ISC, select Security => Secure administration, applications, and infrastructure.
  3. In the Available realm definitions drop-down box, select Federated repositories and click Configure.
  4. Change the Primaryadministrative user name to a username of your choice, such as wesbuser
  5. Select Automatically generated server identity and then click OK.
  6. Enter a password for the user, such as wesbpass and then click OK.
  7. Tick Enable administrative security.
  8. In the Available realm definitions drop-down box, select Federated repositories and click Set as current.
    Figure 6. Setting federated repository as the user registry
    Figure 6
  9. Click Apply.
  10. Select Security => Business Integration Security.
  11. Change both the CommonEventInfrastructureJMSAuthAlias and the SCA_Auth_Alias aliases to use the newly defined username and password, then click OK.
  12. Save the changes to the master configuration.
  13. If you are using Integration Developer, update the server configuration to use the new credentials.
  14. After restarting the server, Integration Developer will need the username and password to connect to the server. Enter these in the server configuration in the Servers view:
    Figure 7. Security credentials for server definition in Integration Developer
    Figure 7
  15. Restart the server.

The server should restart with error-free logs. Check the <server_profile_dir>\logs\server1\SystemOut.log file, or the Console view in Integration Developer while the server is restarting. If there is a problem accessing the server, try switching security off:

  1. Edit the <server_profile_dir>\config\cells\<cell_name>\security.xml file.
  2. Change the value of the enabled attribute of the security node to false.
  3. Restart the server (in any manner possible).

A common problem is to see the state in Integration Developer as Starting… even though the server is started. You can usually fix this by entering the correct credentials, or by changing the Server connection type from RMI to SOAP in the server configuration inside Integration Developer.

Figure 8. Changing to SOAP can alleviate admin connection issues
Figure 8

For your information, the file-based repository is persisted at <server_profile_dir>\config\cells\<cell_name>\fileRegistry.xml.

Running the client

  1. Now run the client, using the same syntax as before. A message about the server’s SSL certificate might appear, because after administrative security is enabled, the communications for the JNDI lookup uses SSL (if possible):
    SSL signer from target host <host> is not found in trust store 
    Here is the signer information 
    (verify the digest value matches what is displayed at the server):
    Subject DN:CN=SHAFT, O=IBM, C=US
    Issuer DN:CN=SHAFT, O=IBM, C=US
    Serial number: 3993808271809965
    Expires:Wed Aug 23 01:32:52 BST 2023
    SHA-1 Digest:A1:D8:A8:B0:AD:86:50:68:4C:BE:51:1E:CD:04:9B:9F:32:AF:A2:4E
    MD5 Digest:FF:65:95:21:1A:37:A1:B7:C3:82:E1:40:B2:61:86:BC
    Add signer to the trust store now? (y/n)
  2. Enter y at the prompt. After accepting, the signer certificate will be imported into the client profile’s default trust store at <client_profile_dir>/etc/trust.p12. The location of the trust store used by launchclient is defined in by the property in the <client_profile_dir>/etc/ssl.client.props file. A pop-up login box will appear:
    Figure 9. Authenticating while connecting to bootstrap port
    Figure 9
  3. If you enter an invalid username or password, the application will fail. Entering the correct values should ensure that the client works as above.
  4. For convenience, you can save the username and password in a properties file for use by the client profile instead of using the default of prompting.
  5. Open the file <client_profile_dir>\properties\sas.client.props using a text editor such as Notepad.
  6. The location of your client profile directory (<client_profile_dir>) depends on whether you are using a standalone installation or the UTE. Examples are D:\WID61\pf\esb, D:\WID61\runtimes\bi_v61\profiles\client, and D:\ESB61\profiles\client.
  7. Set the following properties and save the file:
  8. Optionally, use the PropFilePasswordEncoder tool to XOR encode the password so that it is not visible in plain text. The command syntax is:
  9. Now the client should run exactly as before without the pop-up login box.

Configuring SIBus authentication

This section shows you how to enforce bus security so that a username and password must be supplied for applications to connect to the SIBus.

Applying bus security and configuring applications

When bus security is turned on, any user or process that wants to access a bus must authenticate with a username and password. Furthermore, only designated users can connect to the bus – users in the "bus connector role." Administrative security must be enabled for bus security to have any effect.

  1. In the ISC, select Security => Bus Security. When you access the ISC, you will be redirected to an HTTPS port such as 9043 (default) and required to enter the administrative username and password:
    Figure 10. Bus security configuration panel
    Figure 10. Bus security configuration panel
  2. Repeat the Steps 3-9 below for each of the three buses.
  3. Click on the Disabled entry in the Security column.
  4. Check Enable bus security.
  5. Click Apply:
    Figure 11. Enabling security for each bus
    Figure 11
  6. The Inter-engine authentication alias is already set (it was unspecified by default in V6.0). This prevents unauthorized messaging engines from establishing a connection.
  7. Click Users and groups in the bus connector role.
  8. Click New.
  9. Select User name and type in wesbuser in the text box.
  10. Click OK.
  11. Save changes:
    Figure 12. Adding a user to the bus connector role
    Figure 12

    The above bus configuration is done for you automatically if you create a profile with administrative security enabled.

  12. JMS resources (connection factory and activation spec) related to the weather mediation’s JMS export need to be configured with the appropriate credentials to access the SIBus. This is done by giving them authority to use an alias named SCA_Auth_Alias.
  13. Open Applications => Enterprise Applications > JMSWeatherForecastApp in the ISC.
  14. Click Resource references.
  15. Select SCA_Auth_Alias from the drop-down box underneath the Use default method option.
  16. Check the row associated with the sca/resource/export/JMSWeatherForecastExport_CF resource reference.
  17. Click Apply:
    Figure 13. Mapping the connection factory to an authentication alias
    Figure 13
  18. The table will be updated as shown below:
    Figure 14. Updated resource reference
    Figure 14
  19. Click OK.
  20. Open Resources => JMS => Activation specifications.
  21. Click JMSWeatherForecast.JMSWeatherForecastExport_AS.
  22. Select SCA_Auth_Alias as the Authentication alias, and click OK.
  23. Save the configuration changes and restart the server. The server logs should remain error-free.
  24. Alternatively, you could have set the application security configuration in Integration Developer before deployment by configuring properties of the JMS Export in the JMSWeatherForecast project:
    Figure 15. Setting the J2C authentication alias for Connection and Response Connection
    Figure 15

Common errors and solutions

  • Without the configuration detailed above, messages like the one below will appear in the SystemOut.log file (Console view) while the server is restarting. If you see any of these errors, then re-check the steps above.
  • Activation spec has no authentication alias:
    J2CA0138E: The MessageEndpoint activation failed for ActivationSpec 
    	( and MDB Application
    	due to the following exception: javax.resource.ResourceException: 
    CWSIV0958E: The authorization exception 
    CWSIP0303E: No user specified when creating a connection to secure messaging engine
  • Resource reference for JMSWeatherForecastApp JMS application not supplied with authentication alias (appears when client is run):
    CNTR0020E: EJB threw an unexpected (non-declared) exception 
    	during invocation of method "onMessage" on bean
    	JMSWeatherForecastExportJMS, null)". ...
    CWSIP0303E: No user specified when creating a connection to secure messaging engine
    	on bus SCA.APPLICATION.SHAFTNode05Cell.Bus.
  • User wesbuser not in bus connector role on application bus:
    CWSIV0959E: The authorization exception 
    CWSIP0302E: A user wesbuser is not authorized to access the messaging engine
    	on bus SCA.APPLICATION.SHAFTNode03Cell.Bus. 
    	was thrown while attempting to create a connection to messaging engine...

Updating client to login to bus

If you run the client, an error message will appear such as:

CWSIT0094E: The client was not authorized to connect to bus 
	using the bootstrap server with endpoint shaft:7280:BootstrapBasicMessaging. 
Reason: CWSIT0109E: The application did not specify user ID when attempting authorization
	with the bus SCA.APPLICATION.SHAFTNode04Cell.Bus.

This is because a username and password now need to be supplied to connect to the bus. The client application can accept parameters that are used in the call to createConnection() on javax.jms.ConnectionFactory in The syntax is:

<install>\bin\launchclient ... as before ... 
-day Tue -location UK
-user wesbuser –password wesbpass

Below you can see that the client has successfully connected to the bus, sent a message, and received a response. There is also a warning message, described in the next section.

WSCL0035I: Initialization of the J2EE Application Client Environment has completed.
WSCL0014I: Invoking the Application Client class Main
JMSProxy : CF=JMSWeatherForecast/JMSWeatherForecastExport_CF
JMSProxy : RequestQ=JMSWeatherForecast/JMSWeatherForecastExport_RECEIVE_D
JMSProxy : ResponseQ=JMSWeatherForecast/JMSWeatherForecastExport_SEND_D
[27/08/08 20:46:40:562 BST] 0000000aW UOW=7-fc00fc-22379812:SHAFT org=IBM 
prod=WebSphere component=Application Server thread=[P=395203:O=0:CT]
[:] CWSIT0107W: The specified port 7280, in the endpoint, implied use of the transport
chain BootstrapBasicMessaging. This will result in the transmission of an unencrypted
password between client and server. This is not recommended for security reasons.
JMSProxy : JMSUSER :wesbuser, JMSPASS :wesbpass
JMSProxy : Sending JMS message ...
JMSProxy : Waiting for response message ...
WeatherClient : Response : Success : Sunny

Configuring SIBus confidentiality

In the output of the client with bus security enabled, a message warns about the password being transmitted in plain text. This is a security issue, because the password could be intercepted on the network between the client and the messaging engine on the server, and then used by a potential attacker. Below, we will configure the buses to only allow communication to the buses across SSL encrypted transport chains.

Restricting communications to SSL

First, the three integration buses on the SIBus need to be restricted to allow only SSL encrypted transport chains. Then it will be necessary to perform some configuration on JMS resources related to the use of transport chains.

  1. Open the Security => Bus Security page in the ISC.
  2. Repeat Steps 3-5 below for each of the three buses.
  3. Click on the Enabled entry in the Security column.
  4. Select Restrict the use of defined transport channel chains to those protected by SSL:
    Figure 16. Restricting transport to SSL for each bus
    Figure 16
  5. Click OK.
  6. The default transport chain for the SIBus is unencrypted with a default port of 7276 (7280 in the output below). It is known as InboundBasicMessaging. There is also an SSL encrypted transport chain with a default port of 7286, named InboundSecureMessaging.
  7. If you save the configuration, restart the server, and then run the client, a message like this will appear:
    A client connect to bus SCA.APPLICATION.SHAFTNode04Cell.Bus failed in
    bootstrap server with endpoint shaft:7280:BootstrapBasicMessaging with reason: 
    CWSIT0090E: A bootstrap request was made to bus SCA.APPLICATION.SHAFTNode04Cell.Bus
    using channel chain InboundBasicMessaging. Use of this chain is not permitted by bus 
  8. The connection factory associated with the JMS export needs to be modified to specify secure transport chains that use SSL. The BootstrapSecureMessaging transport chain is used to connect to the bootstrap server. It is not mandatory that this hosts the messaging engines. The InboundSecureMessaging value is used by the bootstrap server to select a suitable messaging engine for the client to connect to. For more information, see Resources at the bottom of the article.
  9. The port (default 7286) can be seen in the ISC at Servers => Application servers > server1 > Ports > SIB_ENDPOINT_SECURE_ADDRESS.
  10. Open the Resources => JMS => Connection factories > JMSWeatherForecast.JMSWeatherForecastExport_CF panel.
  11. Set the Provider endpoints value to server_hostname:sib_endpoint_secure_address_port: BootstrapSecureMessaging.
  12. Set Target inbound transport chain to InboundSecureMessaging:
    Figure 17. Example provider endpoints and transport chain for secure connection
    Figure 17
  13. Click OK then save changes to the master configuration.
  14. Restart the server.

The client should work successfully. It will use the updated provider endpoint value when it accesses the connection factory to make a connection to the bus using the secure transport chain. The client will accept the server certificate, because in an earlier step, we imported it into the trust store used by the launchclient client.

Using SSL client authentication

In this section, you will configure the transport chain of the bus to only allow connections from clients possessing trusted certificates. This feature is called client authentication and applies to SSL configurations.

First, create a new SSL configuration using the same default key and trust stores as the standard default configuration but with client authentication mandatory. You will apply this later to the secure JMS transport chain. You cannot just enable client authentication on the default NodeDefaultSSLSettings SSL configuration because this would also apply to HTTPS, and the ISC would be inaccessible. (Some browsers such as Mozilla Firefox do support client authentication, and so it is possible to import the browser’s personal certificate into the server’s default trust store.)

  1. Open the Security => SSL certificate and key management > SSL configurations page.
  2. Click New.
  3. For Name enter ClientAuthSSLConfiguration.
  4. Select Trust store name to be NodeDefaultTrustStore.
  5. Select Keystore name to be NodeDefaultKeyStore.
  6. Click Apply.
  7. Click Quality of protection (QoP) settings:
    Figure 18. Setting required client authentication on a new SSL configuration
    Figure 18
  8. Select Required in the drop-down for Client authentication, and then click OK.
  9. Now you associate the new SSL configuration with the secure inbound transport chain for SIBus. Open the Application servers > server1 > Messaging engine inbound transports => InboundSecureMessaging panel.
  10. Click SSL inbound channel (SIB_SSL_JFAP).
  11. Select Specific to this endpoint.
  12. Choose ClientAuthSSLConfiguration in the drop-down box, and then click OK:
    Figure 19. Associating new SSL configuration with inbound secure messaging transport
    Figure 19
  13. Save changes and restart the server.
  14. Run the client and it will fail with the message:
    Caused by:
    CWSIC1001E: A client attempted to connect with a remote messaging engine 
    (shaft:7290 - BootstrapSecureMessaging) but the connection cannot be completed. 
    Caused by: 
    Received fatal alert: certificate_unknown
  15. To allow the client to connect, you must import the client’s public certificate into the trust store of the server’s SSL configuration. First export the client profile’s signer certificate:
    	<install>\java\bin\keytool -export -keystore <client_profile_dir>\etc\key.p12
    	-storepass WebAS -storetype PKCS12 -alias default -file <fileToCreate.cert> -rfc
  16. The default password for all the key and trust stores is WebAS and should be changed in a secure environment.
  17. Open the page SSL certificate and key management => Key stores and certificates => NodeDefaultTrustStore => Signer certificates.
  18. Click Add.
  19. Enter the value weatherclient for Alias.
  20. Enter the File name of the exported client certificate. This is the value used for <fileToCreate.cert> expression above.
  21. The Data type is Base64-encoded ASCII data. and then click OK.
  22. Save changes.
  23. The certificate has been imported with an alias of weatherclient:
    Figure 20. Client certificate added to the server’s trust store
    Figure 20

    Now the client will connect successfully because the server will trust the client profile’s signer certificate. That is still the username and password that control access to the SIBus. The SSL client authentication is used to control the connection between the client and the messaging engine on the server.

An alternative for manipulating certificates and key/trust stores is to use the graphical tool IKeyMan available at <install>\bin\ikeyman. The features available in the ISC for working with certificates and key/trust stores have been vastly improved in V6.1. One feature is Retrieve from port (pictured above), which downloads a certificate from a server at a given hostname and port (such as port 80 or 9080) and adds it to a trust store. This technique is an alternative to the command-line approach used in this article.

Other considerations

This article has shown how to authenticate, authorize and protect communications from a JMS client to a WebSphere ESB server. In a deployment environment, the other transports such as HTTP would need to be secured or ideally switched off if not needed. For example, the inbound basic messaging transport chain can be disabled. Another example is the RMI-IIOP (CSIv2) port that by default supports authentication and SSL. It can be configured to require both.

We used client authentication to only trust an explicit set of clients. In practice, using certificates for this purpose does not scale as the number of clients and servers increases, because the time taken to verify that a certificate is trusted increases with the size of the trust store. Also, each client’s signer certificate needs to be imported into each server’s trust store. In practice, when using many clients, usernames and passwords can be used for authentication and authorization, as described, and SSL can be used to ensure confidentiality.

An alternative to self-signed certificates is to use a Certificate Authority (CA) and public key certificates. When the client needs to ensure the identity of the server, it can trust the server’s certificate because it has been digitally signed by the CA.

The default key and trust stores have dummy signers that should be removed and default passwords that should be changed in a deployment environment. For more information on security hardening, see Resources at the bottom of the article.

We used a single user to administer and run the server. We also used the same user for the client and applications running on the server to access resources such as messaging engines. In practice, you should use different users for different security roles. WebSphere ESB also provides role-based security for applications as part of the SCA programming model. There are security qualifiers, applied in Integration Developer, that allow role-base authorization to be defined on a component inside a module. For more information on the role-based security for applications, the server, and the SIBus, see Resources at the bottom of the article.


There are many aspects to ensuring that a solution delivers appropriate security. WebSphere ESB V6.1 and WebSphere Application Server V6.1 both provide many security enhancements compared to V6.0. ne such improvement is that by default, profiles have administrative and bus security enabled. This article showed what is involved in these features and the impact they have on a JMS client. The client was configured to authenticate with the server and all communications were protected by SSL.

There are additional ways to apply security using WebSphere ESB. Some examples are listed in the section above, such as role-based application security defined in Integration Developer. The overall security also depends on the operating system and network environment, including proxies, firewalls, or other security devices such as WebSphere DataPower Appliances. For more information on security hardening, see Resources at the bottom of the article.


The author would like to thank IBM colleagues David Currie, Oliver Dineen, and Alasdair Nottingham for their help with this article.

Contents of download file

The downloadable zip file contains the following files:

  • -- Project interchange file for WebSphere Integration Developer
  • UKWeatherClient.earclient EAR
  • JMSWeatherForecast.earserver EAR
  • UKWeatherService.earserver EAR
  • WeatherMediation.earserver EAR


Code sampleWESB61-JMSSecurityWeatherArticle.zip275 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Business process management on developerWorks

Zone=Business process management, WebSphere
ArticleTitle=Securing JMS connections to WebSphere Enterprise Service Bus V6.1 or V6.2