Connecting to WebSphere v7.0+ with LISA using WAS Thin Client

Document ID:  TEC603877
Last Modified Date:  12/30/2013
{{active ? 'Hide' : 'Show'}} Technical Document Details

Products

  • CA Application Test

Components

  • CA ITKO LISA TEST / FRAME:ITKOTF

Introduction

This page details how to connect to a WebSphere Application Server, version 7.0 or later, using JNDI for EJB or JMS operations.

Websphere Version

This applies to WebSphere Application Server version 7.0 or greater. I have tested it explicitly with v8.0.0.4.

For v6.0 or earlier, see Connecting to WebSphere with LISA using SIBC.

Obtaining the required files and information

You will need to obtain the Jar files and a couple of config files from the WebSphere server itself.

Required information

You will need the following information:

  • WebSphere server name or IP address
  • JNDI user name and password
  • JMS user name and password (This can be different from the JNDI login)

Server ports

You will need to know at least two, possibly three ports on the WebSphere server:

  • Bootstrap port (default 2809)
  • CSIV SSL listener port (default 9403)
  • (possibly) SIB Endpoint port (default 7286)

If you have access to the WebSphere server console then you can find these ports from the main page:

 

Figure 1

Click 'Servers', 'Server Types', and 'WebSphere application servers'. On the right will be a list of servers. Click on the appropriate one.

On the next screen, scroll down to 'Ports' on the right side and expand it:

Figure 2

Here you can find the Bootstrap port, CSIV SSL port, and the SIB Endpoint port.

WebSphere Home and Profile home

You will need to find the WebSphere Home directory and the server Profile Home directory.

The WebSphere Home is typically located here:


C:\Program Files\IBM\WebSphere\AppServer  

The Profile Home is dependent on your WebSphere server name, and is located here:


[WebSphere Home]\profiles\[Server name]  

For example:


C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01  

Jar files

The necessary Jar files are located under WebSphere Home:


[Websphere Home]\runtimes  

For example:


C:\Program Files\IBM\WebSphere\AppServer\runtimes  

In order to use EJBs or JMS you will need these three Jar files:


com.ibm.ws.ejb.thinclient_8.0.0.
jarcom.ibm.ws.orb_8.0.0.jar
com.ibm.ws.sib.client.thin.jms_8.0.0.jar  

Copy those Jar files into LISA HOME/hotDeploy. They will also work in LISA_HOME/lib or LISA_HOME/bin/patches, but it's not necessary.

Config files and SSL keystores

SSL is enabled by default as of WebSphere v7.0. To successfully work with WebSphere you will need two sets of files.

Config files

The config files are located under Profile Home:


[Profile Home]\properties  

For example:


C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\properties  

You will need these two files:


sas.client.props
ssl.client.props  

Copy them to the LISA client machine and remember their full path for later.

SSL Keystores

The SSL Keystore files are located under the Profile Home:


[Profile Home]\etc  

For example:


C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\etc  

You will need these two files:


key.p12
trust.p12  

Copy them to the LISA client machine and remember their full path for later.

Manually building a trust store

For various reasons the trust store that comes from the WebSphere server doesn't seem to work. Even when configured correctly through ssl.client.props, the thin client doesn't seem to recognize the server certificate in trust.p12 when connecting to JNDI. And when connecting to JMS it doesn't appear to use the settings in ssl.client.props at all. To top it off, you can't even inspect trust.p12 yourself because the supplied keystore password is encrypted and WAS does not provide a tool to decrypt it, only to change it.

The only way I found to work around this was to build a trust store from scratch.

Obtaining the server SSL certificate

The easiest way to obtain the server certificate is to simply pretend it's HTTPS and hit the server port with Firefox.

Open Firefox and enter the following URL:


https://[server name]:[CSIV SSL listener port]  

For example:


https://itko-was80:9403  

You can also try hitting using the SIB Endpoint port instead of the CSIV SSL listener port.

You should see the untrusted connection screen:

Figure 3

Click 'Add Exception'. You should see the Add Exception dialog:

Figure 4

Click 'View'. You should see another dialog with the certificate info:

Figure 5

Cilck the 'Details' tab, and then 'Export'.

Figure 6

Enter 'trust.der' and select the format 'X.509 Certificate (DER).

For convenience, you should save the certificate .DER file to the same place where you saved the .p12 files from WebSphere.

Converting the SSL certificate into a Java keystore

Now that you have the server's certificate in a .DER file, you will need to convert it to a Java keystore. For this you will need the keytool utility, which only comes with the full JDK. If you only have the JRE installed then you will need to download the JDK to get keytool.

Once you have keytool, open a command prompt and navigate to the directory where you saved the certificate .DER file.

Run keytool to copy the certificate into a new keystore:


keytool -importcert -keystore trust.jks -file trust.der -alias WAS  

You will be prompted to enter a password for the keystore. Remember this password for later.

Configuring LISA

local.properties

Add the following properties to local.properties:


com.ibm.CORBA.ConfigURL=file:[full path to sas.client.props]
 com.ibm.SSL.ConfigURL=file:[full path to ssl.client.props]
 
 javax.net.ssl.trustStore=[path to your manually generated trust.jks]
 javax.net.ssl.trustStorePassword=[your trust store pssword] 

ssl.client.props

The ssl.client.props file that comes from the Profile Home is set up for the IBM JRE. Since LISA typically uses the SUN JRE you must modify this file.

SSL Provider

Find the following section in ssl.client.props:


com.ibm.ssl.alias=DefaultSSLSettings
 com.ibm.ssl.protocol=SSL_TLS
 com.ibm.ssl.securityLevel=HIGH
 com.ibm.ssl.trustManager=IbmPKIX
 com.ibm.ssl.keyManager=IbmX509
 com.ibm.ssl.contextProvider=IBMJSSE2
 com.ibm.ssl.enableSignerExchangePrompt=gui  

Change the following lines:


com.ibm.ssl.alias=DefaultSSLSettings
 * com.ibm.ssl.protocol=SSL
 * com.ibm.ssl.trustManager=SunX509
 * com.ibm.ssl.keyManager=SunX509
 * com.ibm.ssl.contextProvider=SunJSSE
   com.ibm.ssl.securityLevel=HIGH
 * com.ibm.ssl.enableSignerExchangePrompt=false  

Keystore

Find the following section:


com.ibm.ssl.keyStoreName=ClientDefaultKeyStore
 com.ibm.ssl.keyStore=key.p12
 com.ibm.ssl.keyStorePassword={xor}CDo9Hgw=
 com.ibm.ssl.keyStoreType=PKCS12
 com.ibm.ssl.keyStoreProvider=IBMJCE
 com.ibm.ssl.keyStoreFileBased=true  

Change the following lines:


com.ibm.ssl.keyStoreName=ClientDefaultKeyStore
 * com.ibm.ssl.keyStore=[full path to key.p12]
   com.ibm.ssl.keyStorePassword={xor}CDo9Hgw=
   com.ibm.ssl.keyStoreType=PKCS12
 * com.ibm.ssl.keyStoreProvider=SunJSSE
   com.ibm.ssl.keyStoreFileBased=true  

Truststore

Find the following section:


com.ibm.ssl.trustStoreName=ClientDefaultTrustStore
 com.ibm.ssl.trustStore=trust2.p12
 com.ibm.ssl.trustStorePassword={xor}CDo9Hgw=
 com.ibm.ssl.trustStoreType=PKCS12
 com.ibm.ssl.trustStoreProvider=IBMJCEcom.ibm.ssl.trustStoreFileBased=true  

Basically comment out the existing section and add your own lines:


com.ibm.ssl.trustStore=[path to your manually generated trust.jks]
 com.ibm.ssl.trustStorePassword=[your trust store pssword]
 com.ibm.ssl.trustStoreType=JKS
 com.ibm.ssl.trustStoreFileBased=true
 com.ibm.ssl.trustStoreReadOnly=true
 
 #Com.ibm.ssl.trustStoreName=ClientDefaultTrustStore
 #Com.ibm.ssl.trustStore=[path to trust2.p12]
 #Com.ibm.ssl.trustStorePassword={xor}CDo9Hgw=
 #Com.ibm.ssl.trustStoreType=PKCS12
 #Com.ibm.ssl.trustStoreProvider=SunJSSE
 #Com.ibm.ssl.trustStoreFileBased=true  

Make sure the the line with com.ibm.ssl.trustStoreName does not appear in your uncommented section. For some reason this breaks things.

Configuring the JMS JNDI step

Use the following settings in the Generic JMS step:

  • JNDI Factory Class: com.ibm.websphere.naming.WsnInitialContextFactory
  • JNDI Server URL: iiop://[host name]:[Bootstrap port]
    • example: iiop://itko-was80:2809
  • User: the JNDI user name
  • Password: the JNDI password
  • Advanced -> Second Level Authentication -> JMS User: The JMS user name. Note that this may be different from the JNDI user name.
  • Advanced -> Second Level Authentication -> JMS password: The JMS password. Note that this may be different from the JNDI password.

First try using one of the magnifying glass buttons to browse the JNDI tree. Failure at that point most likely means something is wrong with ssl.client.props.

If that works then try testing the step and sending a JMS message. Failure at that point means there may be something wrong with your local.properties ssl settings.

Note that it may take a couple of seconds the first time you connect to the WAS server. Subsequent operations should go faster because the WAS thing client is doing some caching in the background.

Troubleshooting

Errors

This error happens a lot, and doesn't really tell you a whole lot. Usually it means there was an SSL issue. You might need to enable trace logging to see the actual error.

org.omg.CORBA.TRANSIENT: initial and forwarded IOR inaccessible vmcid: 0x4942f000 minor code: 3591 completed: No

This error usually happens with the WebSphere-supplied trust store, trust.p12. For some reason the Sun JVM has a hard time reading it and can't use it for matching service side certificates:

CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN "CN=itko-was80, OU=itko-was80Node01Cell, OU=itko-was80Node01, O=IBM, C=US" was sent from target host:port "192.168.2.139:9403". The signer may need to be added to local trust store "/Users/kbow/work/platforms/jndi/dist/bin/trust2.p12" located in SSL configuration alias "DefaultSSLSettings" loaded from SSL configuration file "file:/Users/kbow/work/platforms/jndi/dist/bin/ssl.client.props". The extended error message from the SSL handshake exception is: "No trusted certificate found".

This rather lengthy chain of exceptions also happens when the trust store is incomplete or can't be read:


Caused by: com.ibm.websphere.sib.exception.SIResourceException: CWSIT0006E: It was not possible 
to contact any of the specified bootstrap servers. 
Please see the linked exception for further details. Bootstrap connections were attempted to: 
[itko-was80:7286:BootstrapSecureMessaging]
        ...
Caused by: com.ibm.websphere.sib.exception.SIResourceException: CWSIC1001E: A client attempted to connect with a 
remote messaging engine (itko-was80:7286 - BootstrapSecureMessaging) but the connection cannot be completed. 
Ensure the messaging engine is started: exception
        ...
Caused by: com.ibm.ws.sib.jfapchannel.JFapConnectionBrokenException: CWSIJ0056E: An unexpected condition 
caused a network connection to host 192.168.2.139 on port 7286 using chain BootstrapSecureMessaging to close.
        ...
Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: 
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
        ...
Caused by: sun.security.validator.ValidatorException: PKIX path building failed:
 sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
        ...
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification 
path to requested target  

This error occurs if you left the com.ibm.ssl.trustStoreName line uncommented in ssl.client.props:


CWPKI0033E: The keystore located at "trust.jks" failed to load due to the following error: JKS not found.  

Old SIBC Jars present

This error means you still have the old WAS v6.0 SIBC client jars on your classpath:


com.sun.corba.se.impl.transport.SocketOrChannelConnectionImpl <init>
 WARNING: "IOP00410201: (COMM_FAILURE) Connection failure: socketType: IIOP_CLEAR_TEXT; hostname: amca02devic1-b1; port: 0"
 org.omg.CORBA.COMM_FAILURE:   vmcid: SUN  minor code: 201  completed: No    at com.sun.corba.se.impl.logging.ORBUtilSystemException.connectFailure(Unknown Source)
     ...
     at com.sun.corba.se.impl.protocol.CorbaClientDelegateImpl.is_a(Unknown Source)
     ... repeated roughly 1000 timesCaused by: java.net.BindException: Cannot assign requested address: connect
     at sun.nio.ch.Net.connect0(Native Method)  

Connection refused

This error means the JMS Connection Factory is not configured correctly on the WebSphere side:


CWSIA0241E: An exception was received during the call to the method JmsManagedConnectionFactoryImpl.createConnection: 
com.ibm.websphere.sib.exception.SIResourceException: CWSIT0006E: It was not possible to contact any
 of the specified bootstrap servers. Please see the linked exception for further details. 
 Bootstrap connections were attempted to: [localhost:7286:BootstrapSecureMessaging]
         ...
 Caused by: com.ibm.websphere.sib.exception.SIResourceException: CWSIT0007W: It is not possible to contact 
 the bootstrap server at localhost:7286:BootstrapSecureMessaging because of exception: 
 com.ibm.websphere.sib.exception.SIResourceException: CWSIC1001E: A client attempted to connect
 with a remote messaging engine (localhost:7286 - BootstrapSecureMessaging) but the connection cannot be completed.
  Ensure the messaging engine is started: exception com.ibm.ws.sib.jfapchannel.JFapConnectFailedException: 
  CWSIJ0063E: A network connection to host name localhost/127.0.0.1, port 7,286 cannot be established.
         ...
 Caused by: java.net.ConnectException: Connection refused  

Notice the hostname and port mentioned in the error: localhost:7286. WebSphere is send us the wrong connection information for the connection factory.

This must be fixed through the WebSphere console:

Figure 7

Click on 'Resources', 'JMS', and 'Connection Factories'. Then click on the correct connection factory on the right.

Scroll down to the 'Provider endpoints' field:

Figure 8

The actual format of this field is a comma-delimited list of endpoint addresses. Typically all you really need to enter is just the WebSphere server's host name.

Turning on the trace log

Add the following lines to local.properties:


com.ibm.CORBA.Debug=true
 com.ibm.CORBA.CommTrace=true
 com.ibm.CORBA.Debug.Output=[full path to client.log]  

client.log can be located wherever you like.

This will cause the WebSphere Thin Client to output a ton of logging.

Please help us improve!

Will this information enable you to resolve your issue?

Please tell us what we can do better.

{{feedbackText.length ? feedbackText.length : '0'}}/255

{{status}}

Not what you were looking for?

Search Again >

Product Information

Support by Product >

Communities

Join a Community >

Chat with CA

Just give us some brief information and we'll connect you to the right CA ExpertCA sales representative.

Our hours of availability are 8AM - 5PM CST.

All Fields Required

connecting

We're matching your request.

Unfortunately, we can't connect you to an agent. If you are not automatically redirected please click here.

  • {{message.agentProfile.name}} will be helping you today.

    View Profile


  • Transfered to {{message.agentProfile.name}}

    {{message.agentProfile.name}} joined the conversation

    {{message.agentProfile.name}} left the conversation

  • Your chat with {{$storage.chatSession.messages[$index - 1].agentProfile.name}} has ended.
    Thank you for your interest in CA.


    Rate Your Chat Experience.

    {{chat.statusMsg}}

agent is typing