Integrate IBM® MQ Service

In this procedure, you will learn how to integrate Kaazing Gateway and IBM WebSphere MQ, an IBM standard for program-to-program messaging across multiple platforms, using the ibmmq (see IBM® MQ Services for Kaazing Gateway) and jms (see JMS Services for Kaazing Gateway) services.

Notes:

To Integrate IBM® MQ 8.0 using the ibmmq Service

  1. Download and install IBM® MQ 8.0 following the instructions in the IBM® MQ documentation. The directory that contains the IBM® MQ installation (for example, C:\Program Files\IBM\WebSphere MQ on Windows) is referred to as MQ_HOME. Use of the MQ 8.0 client jars is required for the ibmmq service, but the service can be used to connect to prior versions of IBM® MQ if needed (for example, WebSphere MQ 7.1 or 7.5).
  2. Copy the following JAR files from MQ_HOME/java/lib to GATEWAY_HOME/lib.
    • com.ibm.mq.allclient.jar
    • fscontext.jar
    • jms.jar
    • providerutil.jar
  3. Open the file GATEWAY_HOME/conf/gateway-config.xml in a text editor and add the ibmmq service element.
    • Here is an example with no JNDI initialContext:
      <service>
       <name>IBM MQ JMS Service</name>
       <description>Optimized JMS Service for IBM MQ</description>
       <accept>ws://localhost:8001/jms</accept>
      
       <type>ibmmq</type>
      
       <properties>
        <queue.manager>QM1</queue.manager>
        <server.channel>SYSTEM.DEF.SVRCONN</server.channel>
        <host>mq.acme.com</host>
        <port>1414</port>
        <!-- other properties, as on the jms service, for example: -->
        <queue.maximum.pending.acknowledgments>10</queue.maximum.pending.acknowledgments>
        </properties>
      </service>
      
    • Here is an example using an initialContext for finer-grained control over MQ options (in this case, ibmmq is configured in much the same way as the jms service):
      <service>
       <name>IBM MQ JMS Service</name>
       <description>Optimized JMS Service for IBM MQ with initial context</description>
       <accept>ws://localhost:8001/jms</accept>
      
       <type>ibmmq</type>
      
       <properties>
        <connection.factory.name>ConnectionFactory</connection.factory.name>
        <context.lookup.topic.format>%s</context.lookup.topic.format>
        <context.lookup.queue.format>%s</context.lookup.queue.format>
        <env.java.naming.factory.initial>com.sun.jndi.fscontext.RefFSContextFactory</env.java.naming.factory.initial>
      
        <!-- The location of the .bindings file -->
        <env.java.naming.provider.url>file:/bindings_file_location</env.java.naming.provider.url>
        <destination.strategy>context</destination.strategy>
       </properties>
      </service>
      
  4. If using an initial context, do the following:
    1. Ensure that you have the .bindings file, which contains the initial context objects (connection factory, queue manager, topics, queues, etc).
    2. Replace bindings_file_location in the env.java.naming.provider.url element with the file path to the JNDI .bindings file folder for the connection to the broker. Do not include the .bindings file name in the file path. For example, file:/C:/JNDI-Directory (Windows) or file:/Users/johndoe/Desktop/JNDI-Directory (Mac and Linux).
  5. Save the configuration file. To test the configuration, see Verifying IBM® MQ Integration.

To Integrate IBM® MQ 8 using the jms Service

  1. Download and install IBM® MQ following the instructions in the IBM® MQ documentation. The directory that contains the IBM® MQ installation (for example, C:\Program Files\IBM\WebSphere MQ on Windows) is referred to as MQ_HOME.
  2. Depending on which version of IBM® MQ you are using, do one of the following:
    • If you are using IBM® MQ 8.0, copy the following JAR files from MQ_HOME/java/lib to GATEWAY_HOME/lib.
      • com.ibm.mq.allclient.jar
      • fscontext.jar
      • jms.jar
      • jndi.jar
      • providerutil.jar
    • If you are using IBM® MQ 7.1 or 7.5, copy the following JAR files from MQ_HOME/java/lib to GATEWAY_HOME/lib.
      • com.ibm.mq.jar
      • com.ibm.mq.jmqi.jar
      • com.ibm.mqjms.jar
      • com.ibm.mq.headers.jar (required for WebSphere client library version 7.5.0.0)
      • connector.jar
      • dhbcore.jar
      • fscontext.jar
      • jms.jar
      • jndi.jar
      • jta.jar
      • providerutil.jar
  3. Open the file GATEWAY_HOME/conf/gateway-config.xml in a text editor and locate the jms service element (search for "jms").
  4. Ensure that you have the .bindings file, which contains the queue manager, initial context, topic name, and queue name. You will need the location of this .bindings file for the next step.
  5. Modify the properties element of the jms service with the following:
    <properties>
      <connection.factory.name>ConnectionFactory</connection.factory.name>
      <context.lookup.topic.format>%s</context.lookup.topic.format>
      <context.lookup.queue.format>%s</context.lookup.queue.format>
      <env.java.naming.factory.initial>
        com.sun.jndi.fscontext.RefFSContextFactory
      </env.java.naming.factory.initial>
     
      <!-- The location of the .bindings file -->
      <env.java.naming.provider.url>
        file:/bindings_file_location
      </env.java.naming.provider.url>
      <!-- Dynamic destinations support; omit for static destinations -->
      <destination.strategy>context</destination.strategy>
    </properties>
    
  6. Replace bindings_file_location in the env.java.naming.provider.url element with the file path to the JNDI .bindings file folder for the connection to the broker. Do not include the .bindings file name in the file path. For example, file:/C:/JNDI-Directory (Windows) or file:/Users/johndoe/Desktop/JNDI-Directory (Mac and Linux).
  7. Save the configuration file. To test the configuration, see Verifying IBM® MQ Integration.
Notes:

Verifying IBM® MQ Integration

To verify that the IBM® MQ integration is working, perform the following steps:

  1. Start IBM® MQ.
  2. Start the Gateway as described in Setting Up the Gateway and Clients.
  3. Download or fork the Kaazing JavaScript JMS tutorial application from Github at https://github.com/kaazing/javascript.client.tutorials.
  4. Follow the steps for building the JMS tutorial: https://github.com/kaazing/javascript.client.tutorials/blob/develop/README.md.
  5. In a browser, navigate to the Node.js server you started at http://localhost:3000/.
  6. Enter the value for Location as ws://localhost:8001/jms.
  7. Change the value of all Destination fields to /topic/testTopic.
  8. Click Connect.
  9. The message "CONNECT: ws://localhost:8001/jms" should appear in the log window followed by the message "CONNECTED: ID:id_value".
  10. Click Subscribe.
  11. Click Send. You should see the message that you sent in the message log.

Note: Because you are using a JMS provider that does not support individual message acknowledgement, you must ensure your client applications acknowledge each message received from a queue or durable subscriber. Otherwise, the client will receive only one message from that queue or durable subscriber.

To Configure an Encrypted (TLS) Connection Between the Gateway and IBM® MQ

You can encrypt network communication between the Gateway hosting the ibmmq service, and IBM® MQ using the ibmmq service property cipher.suite or by configuring properties in the initial context using MQ Explorer or the JMS administration command-line tool.

One-Way or Two-Way Encryption

You can configure one-way or two-way TLS encryption between the Gateway and IBM® MQ. You can have one-way trust where the Gateway trusts the IBM® MQ server, and you can add two-way trust where the IBM® MQ also trusts the Gateway. For the Gateway to trust IBM® MQ, the Gateway must contain a public certificate for the IBM® MQ server in the truststore of the Gateway. For IBM® MQ to trust the Gateway, the Gateway must contain its own private identity certificate in its keystore, and present that certificate to the IBM® MQ server when requested.

TLS Configuration Procedure

The following steps describe how to implement two-way TLS encryption between the Gateway and IBM® MQ. If you only want to implement one-way encryption, simply skip the other encryption method.

  1. Do one of the following:
    1. Encrypt the connection using cipher.suite:
      1. Add the cipher.suite property to the properties section of the ibmmq service. There is no default value for cipher.suite. If this property is not specified then the connection to MQ will not be encrypted.
      2. Add the cipher suite to use as the value of cipher.suite. You can use any cipher suite supported by IBM® MQ. For a list, see SSL/TLS CipherSpecs and CipherSuites in IBM MQ classes for JMS.

        Here is an ibmmq example configuration using cipher.suite:

        <service>
          <name>IBM MQ JMS Service</name>
          <description>Optimized JMS Service for IBM MQ</description>
          <accept>ws://${gateway.hostname}:${gateway.extras.port}/jms</accept>
        
          <type>ibmmq</type>
        
          <properties>
            <queue.manager>QM1</queue.manager>
            <server.channel>SSL.SVRCONN</server.channel>
            <host>mq-server</host>
            <port>1414</port>
            <ssl.cipher.suite>SSL_RSA_WITH_AES_128_CBC_SHA256</ssl.cipher.suite>
            <!-- other (optional) ibmmq service properties -->
            <queue.session.worker.count>10</queue.session.worker.count>
            <!-- other properties in common with the jms service, for example: -->
            <queue.session.count>2</queue.session.count>
            <queue.maximum.pending.acknowledgments>10</queue.maximum.pending.acknowledgments>
          </properties>
        </service>
        
    2. Encrypt the connection using initial context:
      1. The ibmmq service supports the use of the following properties set on the initial context. You can set these using MQ Explorer or the JMS administration command-line tool.

        Property label in MQ Explorer1 Property name for JMSAdmin2 Description Default Value
        CipherSuite SSLCIPHERSUITE Name of the cipher suite to use. None. If you do not use a cipher suite, the connection to MQ is not encrypted and all other SSL related properties are ignored.
        Peer name SSLPEERNAME If this property is set, the identifying certificate presented by the server at connect-time must match this distinguished name. None. No checking of the certificate name is performed.
        Certificate revocation list SSLCRL Specifies 0 or more CRL (Certificate Revocation List) servers. None. No checking of certificate revocation is performed.
        FIPS required SSLFIPSREQUIRED Specifies whether an SSL connection must use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS). NO (false).
        Reset count SSLRESETCOUNT Specifies the total number of bytes sent and received by a connection before the secret key for encryption is renegotiated. 0 (the secret key is never renegotiated).

        1ConnectionFactory properties under SSL
        2See IBM MQ documentation: Properties of IBM MQ classes for JMS objects

  2. Configure the Gateway truststore with the public IBM® MQ certificate. The following example shows how to import the certificate into the truststore, called truststore.db, located in GATEWAY_HOME/conf/:
    keytool -importcert -keystore GATEWAY_HOME\conf\truststore.db -storepass changeit -trustcacerts -alias host.corp.example.com -file certificate.cer

    For local development and testing, you can use a self-signed certificate. See step 9 in Secure the Gateway Using Self-Signed Certificates. For production, use a certificate from a trusted Certificate Authority. Follow the steps in Secure Gateway-to-Server Connections. For more information, see the keytool documentation

  3. Configure the Gateway keystore with the private identity certificate that the Gateway will present to IBM® MQ. The following example shows how to import the certificate into the default keystore, called keystore.db, located in GATEWAY_HOME/conf/:
    keytool -importcert -keystore GATEWAY_HOME\conf\keystore.db -storetype JCEKS -storepass password -alias hostname -file example.cer

    For local development and testing, you can use a self-signed certificate. For information on creating the Certificate Signing Request (CSR) and importing the trusted certificate into the keystore, see the keytool documentation.

  4. Verify the secure connection. Run IBM® MQ. Run the Gateway hosting the ibmmq service and verify that there are no startup errors. If there are errors, ensure that the certificate that you put in the truststore of the Gateway contains the host name of the IBM® MQ server, and the certificate you put in the keystore of the Gateway contains the host name of the Gateway server.

For more information on using certificates, see Secure Network Traffic with the Gateway.

See Also