Hermes JMS client documentation lacks of how to connect to Websphere Application Server (WAS) messaging. Most googled receipts with Websphere keyword refer to MQ. While it is possible to expose WAS internal service integration bus (SIB) as MQ link, I failed on that part as WAS was throwing at me 2035 error no matter what I tried. I stepped back to use CORBA for native dialog with SIB bus.
Playing with asynchronous communication with processes on IBM BPM I wanted some GUI for remote client sequences. That pushed me to use Hermes JMS as it is pluggable to SoapUI testing tool for JMS scenarios. A lot of time spent on trial-and-error motivated me to make this quick guide helping others to wire Hermes with WAS.
If your server environment is experimental e.g. for development, so that security is irrelevant you can use basic configuration. For real environments continue with SSL part to completely setup JMS client.
Basic configuration
In short you need to get thin client libraries from WAS runtime installation, configure connection in HermesJMS session and relax default security policies on WAS server for non-SSL connections.
- Go to <WAS_HOME>/runtimes on server side and copy into <HERMES_HOME>/lib on client side following thin client jars:
- com.ibm.ws.sib.client.thin.jms_8.5.0.jar – JMS for SIB bus
- com.ibm.ws.orb_8.5.0.jar – CORBA protocol
- com.ibm.ws.ejb.thinclient_8.5.0.jar – needed for JNDI lookup of connection factories.
- In HermesJMS open Preferences window, switch to Providers tab, create new group e.g. was855sib and add these jars to this group.
Add session
Add provider
- Create new Session e.g. was855 and choose was855sib in loader dropdown in connection factory section. If dropdown does not show recently added provider, close dialog and reopen it (edit menu item on session object).
- Add initialContextFactory, providerURL and binding properties to connection factory.
Use com.ibm.websphere.naming.WsnInitialContextFactory as initial context factory.
Provider URL is bootstrap server in format iiop://<servername>:<bootstrapport>. Server name is DNS name, bootstrap port is taken from WAS configuration to be found in admin console under: servers / server types / websphere application server / <servername> / ports / BOOTSTRAP_ADDRESS.
Binding is JNDI name of connection factory object to be used. In WAS admin console: resources / JMS / (queue|topic) connection factories / <object_name> / JNDI name.Note: in WAS environment I was connecting to (screenshot aside) the binding was misleadingly named with fully qualified Java class name notation, usually binding naming convention makes it looking like “jms/QueueName”.
- Check if SIB has security enabled (in admin console: security / bus security / <bus_name> / security / enable bus security). From “authorization policy” section pick a user name that is authorized to connect to the bus. In HermesJMS session dialog, provide username and password details for that user.
- Allow non-SSL communication with SIB. In WAS admin console: security / global security / RMI/IIOP security / CSIv2 inbound communications, set Transport to SSL-supported to let both secure and insecure communications. From WAS 8.0 remote invocation allows only SSL by default.
- If your connection factory enforces secure transport and endpoint than reconfigure it with non-SSL ones. In WAS admin console: resources / JMS / (queue|topic) connection factories / <object_name>, replace Target inbound transport chain from InboundSecureMessaging to InboundBasicMessaging and in Provider endpoints replace fragment BootstrapSecureMessaging with BootstrapBasicMessaging.
- After saving all changes to WAS configuration restart server to apply new security policies.
- Run HermesJMS, discover objects for was855 and open queue/topic accessible to given user to verify JMS client works fine.
Bus security
CORBA security
QCF security
SSL configuration
Following steps extend basic setup with importing certificates from WAS server, configuring SSL and RMI properties of thin client and adding this configuration to HermesJMS bootstrap.
- For SSL enabled client points 6 and 7 of basic configuration can be skipped: SSL can be enforced (SSL-required) and transport/endpoints secured.
- Locate keystore and truststore on server side. Navigate to <WAS_HOME>/profiles/<profilename>/config/cells/<cellname>/nodes/<nodename>.
- If you are using Oracle JRE on client side convert stores to different format like JKS using keytool as below. Using PKCS12 format of .p12 files on client with non-IBM JVM leads to SSL errors e.g protocol negotiation fails on handshake. Note that WebAS is default WAS keystore/truststore password, while WebAS_JKS is password for JKS stores. Also aliases differ for keystore and truststore, named root and default respectively.
keytool -v -importkeystore -srckeystore trust.p12 -destkeystore trust.jks \ -srcstoretype pkcs12 -deststoretype jks -srcstorepass WebAS -deststorepass WebAS_JKS \ -alias root -srckeypass WebAS -destkeypass WebAS_JKS
keytool -v -importkeystore -srckeystore key.p12 -destkeystore key.jks \ -srcstoretype pkcs12 -deststoretype jks -srcstorepass WebAS -deststorepass WebAS_JKS \ -alias default -srckeypass WebAS -destkeypass WebAS_JKS
- Copy key.jks and trust.jks (or key.p12 and trust.p12 if client runs on IBM JVM) to client side, e.g under <HERMES_HOME>/etc.
- On server side navigate to <WAS_HOME>/profiles/<profilename>/properties and copy ssl.client.props and sas.client.propsto client side e.g. same location where thin client jars are placed.
- Modify ssl.client.props to encompass non-IBM JVN on client side. Replace HERMES_HOME with real path. For IBM JVM on client side only keystore and truststore locations must be changed, compare with this document.
com.ibm.ssl.alias=DefaultSSLSettings com.ibm.ssl.protocol=SSL com.ibm.ssl.securityLevel=HIGH com.ibm.ssl.trustManager=SunX509 com.ibm.ssl.keyManager=SunX509 com.ibm.ssl.contextProvider=SunJSSE # KeyStore information com.ibm.ssl.keyStore=HERMES_HOME/etc/key.jks com.ibm.ssl.keyStorePassword=WebAS_JKS com.ibm.ssl.keyStoreType=JKS com.ibm.ssl.keyStoreProvider=SUN com.ibm.ssl.keyStoreFileBased=true # TrustStore information com.ibm.ssl.trustStore=HERMES_HOME/etc/trust.jks com.ibm.ssl.trustStorePassword=WebAS_JKS com.ibm.ssl.trustStoreType=JKS com.ibm.ssl.trustStoreProvider=SUN com.ibm.ssl.trustStoreFileBased=true
- Modify sas.client.props to enter credentials for CORBA authorization. Example for admin/admin as username and password
com.ibm.CORBA.loginSource=properties com.ibm.CORBA.loginUserid=admin com.ibm.CORBA.loginPassword=admin
- Configure Hermes start script to pass references to configuration files on bootstrap. Using connection factory userPropertiesFile property does not work. On Windows OS modify hermes.bat adding following lines before last line:
set SSL_RMI_DEFS= ^ -Dcom.ibm.SSL.ConfigURL=file:/c:/Developer/HermesJMS/lib/was_sib/ssl.client.props ^ -Dcom.ibm.CORBA.ConfigURL=file:/c:/Developer/HermesJMS/lib/was_sib/sas.client.props set HERMES_OPTS=%HERMES_OPTS% %SSL_RMI_DEFS%
assuming that c:/Developer/HermesJMS/lib/was_si is location of property files copied to client side.
- Restart Hermes JMS, discover objects for was855 and open queue/topic accessible to given user to verify JMS client works fine using SSL.
Hi,
Thanks for a great article. There is a misleading screenshot, but overall, it was very good.
In your screenshot of the binding property, you’re specifying javax.jms.QueueConnectionFactory, but in your text, you’re specifying the JNDI name to be entered. Perhaps you could update the screenshot? Normally, JNDI names are in the format of jms/HermestTestQueue or something.
Thanks,
Mattias Green
Hi Mattias, I was working on VM with WAS that had JNDI name specified with dot-notation looking like Java class name – quite unfortunate I agree, so that I will clarify it in the text. Thank you for you vigilance!
Thanks a ton Andy. This article was very useful.