Connecting IBM App Connect to an IBM MQ queue manager in a private network

Learn how to deploy an IBM® App Connect Enterprise Toolkit integration, which interacts with an IBM MQ queue manager in a private network, to an integration server or integration runtime.

Note: This scenario assumes that you have a running App Connect Dashboard instance that was created within an IBM Cloud Pak for Integration environment or an independent IBM App Connect Operator deployment.

Scenario

This scenario illustrates how to use the App Connect Dashboard to deploy a Toolkit integration, which contains a message flow that is configured to interact with a queue manager. The IBM MQ server is hosted in a private network (for example, behind a firewall in an on-premises system), which means that IBM App Connect needs to be correctly configured to securely access the server.

The scenario walks you through the steps for setting up this configuration, and assumes that you have a BAR file that you can deploy if you want to try out the steps.

You begin by creating a switch server in your cluster, and an integration server in your App Connect Enterprise on-premises system, which are both needed to configure secure connectivity between your containerized environment and your private network. Next, you configure the App Connect Enterprise integration server to run as a dedicated switch client by creating and configuring a private network connection with a switchclient.json file.

You then set up port forwarding to allow connections to the remote database port (and host) through an SSH tunnel. You do so by creating a configuration object of type Private Network Agent, which supplies a local port for the integration server or integration runtime, and the remote port and host to forward messages to.

IBM MQ uses the following mechanisms to provide access to one or more queue managers.

A client channel definition table (CCDT) lists the queue managers that you can connect to.
A security exit that is called mqccred allows different passwords to be used for each system.

Therefore, to complete the queue manager connection configuration, you need to provide additional mandatory details, which can be used to create configuration objects:

A CCDT in JSON format, which provides client-connection channel definitions for the queue manager. Supply these details by creating a configuration object of type mqccdt.
The user ID and password credentials for the queue manager in the CCDT, which you want to pass in the mqccred security exit. The mqccred security exit needs to be referenced in the CCDT file. Supply these details by creating a configuration object of type mqccred.ini.
A policy project, which, for example, contains a policy for the IBM MQ message flow nodes that connect to the IBM MQ instance. This policy project references the CCDT and includes a policy that contains the connection details to the queue manager. Supply these details by creating a configuration object of type Policy project.
Credentials for connecting to the queue manager. Supply these details by creating a configuration object of type setdbparms.txt.

Apply the configuration objects (Private Network Agent, mqccdt, mqccred.ini, Policy project, and setdbparms.txt) to the integration server or integration runtime custom resource before you deploy it.

Creating an integration server or integration runtime that is configured to connect to an IBM MQ queue manager in a private network

These instructions provide the complete sequence for configuring a private network connection and deploying an integration.

In these instructions, step 1 and step 2 are considered one-time tasks because the switch server and switch client can be used for multiple integration server or integration runtime deployments that access a private network. Also, you can create the configuration objects before you create the integration server or integration runtime (as detailed in the instructions), or you can do so while creating the integration server or integration runtime.

To configure a private network connection and deploy an integration server or integration runtime, complete the following steps:

Create a switch server and a designated switch client that you can use to configure secure connectivity between your containerized environment and your private network.
1. From your cluster, create a switch server in the same namespace as your App Connect Dashboard instance. Link this switch server to the Dashboard instance by setting spec.switchServer.name in the Dashboard custom resource (CR) to the switch server name.
2. From your App Connect Enterprise 12.0.7.0 or later environment, create an integration server to use as your designated switch client.
For more information, see Creating a switch server.

Configure the App Connect Enterprise integration server to run as a dedicated switch client. To do so, you need to configure a private network connection.

From the App Connect Dashboard, open the Private network connections page and then create a private network connection.
Use the Actions menu for the private network connection to view the setup instructions and to download the switch client configuration file (named switchclient.json) to a location on your computer.

Edit the switchclient.json file to add the IBM MQ hostname (or IP address) and port to the endpoints array, as shown in the following example.

{
  "id": "fbda61eb-0e17-4bd2-a61d-9d202c1b2303",
  "admin": "enabled",
  "callableFlow": "enabled",
  "endpoints": [
    {
      "name": "My MQ endpoint descriptive name",
      "hostname": "192.0.2.24",
      "port": 1414,
      "useTLS": false,
      "certs": {
        "key": "",
        "cert": "",
        "ca": [
          ""
        ],
        "rejectUnauthorized": true
      }
    }
  ],
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}

Copy the updated switchclient.json file to the workdir/config/switch directory for the IBM App Connect Enterprise integration server that you created earlier. Then, start your integration server to run it as a switch client that communicates with the switch server.

Create a configuration object of type Private Network Agent to set up port forwarding to tunnel connections from a local listening port to the remote port on which the IBM MQ server listens.
1. Prepare the switchclient.json file that is required for this configuration type.
  1. Save a copy of the completed switchclient.json file from the previous step to a temporary location. Make a note of the hostname and port values in this file.
  2. Edit the file to remove the id, admin, and callableFlow entries, and the endpoints array lines. The final result should be similar to this:
```
{
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}
```
  3. Insert the following lines for a listeners array directly after the starting curly bracket ({), where:
    - localPortNumber is a local port number of your choice, through which all connections to the remote queue manager port on the private network are forwarded.
    - remoteHost is the IBM MQ hostname or IP address from the pre-edited switchclient.json file.
    - remotePortNumber is the IBM MQ port number from the pre-edited switchclient.json file.
```
  "listeners": [{
  "localPort": localPortNumber,
  "remoteHostname": "remoteHost",
  "remotePort": remotePortNumber
}],
```
    The completed file should be similar to this. This example indicates that connections to local port 9000 should be forwarded to the remote port 1414 on which the queue manager host 192.0.2.24 listens.
```
{
  "listeners": [{
  "localPort": 9000,
  "remoteHostname": "192.0.2.24",
  "remotePort": 1414
}],
  "switch": {
    "url": "wss://default-switch-server-switch-abcdefgh1jg.apps.appc-c-vir-d1.vz8y.p1.abc.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nxxx\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nyyy\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nzzz\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  },
  "displayName": "pnc-wed-14-jun-2023-07-25-14-gmt-553"
}
```
2. From the App Connect Dashboard, use the switchclient.json file to create a configuration object of type Private Network Agent. For more information, see Private Network Agent type.

Create a configuration object of type mqccdt, which contains client-connection channel definitions for the queue manager that the integration server or integration runtime needs to connect to. This configuration type requires a JSON CCDT file.

On the IBM MQ server, create a JSON CCDT file (for example mqccdt.json). Complete this file as follows:

Specify the channel name, channel, description, queue manager name, and TLS definition.
Set the queue manager host to the local host (localhost), and set the port to the localPort value in the switchclient.json file from the previous step.

A typical format for the JSON CCDT file is as follows.

{
  "channel":
  [
    {
      "name": "channelName",
      "type": "clientConnection",
      "general":
      {
        "description": "channelDescription"
      },
      "clientConnection":
      {
        "queueManager": "queueManagerName",
        "connection":
        [
          {
            "host": "localhost",
            "port": localPort
          }
        ]
      },
      "transmissionSecurity":
      {
        "cipherSpecification": "ANY_TLS12_OR_HIGHER"
      },
      "exits":
      {
        "security":
        {
          "name": "mqccred(ChlExit)",
          "userData": "DEBUG,NOCHECKS"
        }
      }
    }
  ]
}

The following example shows a completed file.

{
  "channel":
  [
    {
      "name": "CLOUD.APP.SVRCONN",
      "type": "clientConnection",
      "general":
      {
        "description": "An SSL channel"
      },
      "clientConnection":
      {
        "queueManager": "pslMQMgr",
        "connection":
        [
          {
            "host": "localhost",
            "port": 9000
          }
        ]
      },
      "transmissionSecurity":
      {
        "cipherSpecification": "ANY_TLS12_OR_HIGHER"
      },
      "exits":
      {
        "security":
        {
          "name": "mqccred(ChlExit)",
          "userData": "DEBUG,NOCHECKS"
        }
      }
    }
  ]
}

From the App Connect Dashboard, use the JSON CCDT file to create a configuration object of type mqccdt. For more information, see mqccdt type.

Create a configuration object of type mqccred.ini that contains user ID and password credentials for authenticating to the IBM MQ queue manager. This configuration type requires an mqccred.ini file.
1. In the mqccred.ini file, specify the queue manager name from your JSON CCDT file in the previous step, and then specify your authentication credentials. The Force=TRUE setting replaces any application-supplied user ID and password with those from the mqccred.ini file.
  A typical format for the mqccred.ini file is as follows.
```
QueueManager:
Name=queueManagerName
User=userID
OPW=password
Force=TRUE
```
  The following example shows a completed file.
```
QueueManager:
Name=MYQMGR
User=daddio
OPW=t0psecret
Force=TRUE
```
2. From the App Connect Dashboard, use the mqccred.ini file to create a configuration object of type mqccred.ini. For more information, see mqccred.ini type.
Create a configuration object of type Policy project that contains a policy project for the IBM MQ queue manager. This configuration type requires the policy project in a compressed file in .zip format.
Use the .zip file to create a configuration object of type Policy project. For more information, see Policy project type.
Create a configuration object of type setdbparms.txt that contains authentication credentials for connecting to the queue manager. This configuration type requires a setdbparms.txt file.
1. In the setdbparms.txt file, define the queue manager authentication credentials.
  The following example shows a sample format of the file contents.
```
mqsisetdbparms --work-dir /home/aceuser/ace-server/ --resource mq::mqcred -u myUserID -p myPassword
```
2. From the App Connect Dashboard, use the setdbparms.txt file to create a configuration object of type setdbparms.txt. For more information, see setdbparms.txt type.
From the App Connect Dashboard, use your BAR file to create an integration server or integration runtime as follows:
1. From your App Connect Dashboard instance, click the Dashboard icon in the navigation panel.
2. If you are deploying an integration server, click Deploy integrations on the Servers page. If you are deploying an integration runtime, click Deploy integrations on the Runtimes page. Then, click Next.
3. Choose Quick start integration as the type of integration and click Next.
4. Provide the BAR file that you want to deploy and click Next.
5. From the Configuration view, select each of the configuration objects of the following types, which you created earlier.
  - Private Network Agent
  - mqccdt
  - mqccred.ini
  - Policy project
  - setdbparms.txt
  Then, click Next.
6. From the Properties view, define the following details for the integration server:
  1. Give the integration server or integration runtime a name, and ensure that the appropriate license values are specified.
  2. If you are deploying an integration server, ensure that the Designer flows mode is set to disabled, which is required when deploying a Toolkit integration.
  3. Accept the remaining defaults and then click Create. The integration server or integration runtime starts and is ready to handle messages. (You might need to refresh the page to see the Started state on the integration server or integration runtime tile in the Dashboard.)
  4. Test your flow.
For more information, see Creating an integration server to run IBM App Connect Enterprise Toolkit integrations and Creating an integration runtime to run your BAR file resources.