Connecting to a secured WebSphere MQ queue manager

You can configure a connection to a secured local or remote WebSphere® MQ queue manager, by setting properties on an MQ node or in an MQEndpoint policy.

Before you begin

Read the topic Configuring connections to WebSphere MQ.
Ensure that the required queue manager has been created on the WebSphere MQ server.
Ensure that the user ID that is running the integration node has the necessary permissions to access the queue manager.

About this task

When you configure an MQ connection from an MQ node to a WebSphere MQ queue manager, you can optionally configure the connection to use a security identity for authentication, SSL for confidentiality, or both. The security identity, which passes user name and password security credentials to the queue manager, can be used on connections to local or remote queue managers. For connections to remote queue managers, you can choose whether to use the SSL protocol to provide confidentiality on the client connection. IBM Integration Bus supports a subset of the SSL functionality that is supported by WebSphere MQ.

You can use the Security identity property on the MQ node or MQEndpoint policy to pass a user name and password to the queue manager, by specifying a security identity that contains those credentials. The identity is defined using the mqsisetdbparms command.

You can specify that the SSL protocol is to be used when a client connection is made to a remote queue manager, by selecting the Use SSL property on the MQ node or MQEndpoint policy. You can use SSL for client connections that are configured using either the MQ client connection properties or a client channel definition table (CCDT). If you specify SSL on the client connection, you must also specify the location of the SSL key repository by using the mqsichangeproperties command. The SSL key repository is created using the WebSphere MQ GSKit, and it holds the required private and public certificates appropriate to the chosen certificate policy for the queue manager. The SSL key repository password stash file key repository file name.sth, which is created using WebSphere MQ GSKit, must be located in same folder as the key repository.

You can define the security properties for a local or client connection on an MQ node by using the MQ Connection properties on the following nodes:

MQInput
MQOutput
MQGet
MQReply

You can also set the properties by using an MQEndpoint policy. For more information, see MQEndpoint policy.

Procedure

Follow these steps to complete the configuration of the integration node:

If your WebSphere MQ queue managers require a user name and password, you can use the mqsisetdbparms command to provide them for the secured connection. You can specify these credentials for all MQ connections (mq::MQ), for all connections to a specified queue manager (mq::QMGR::QMName), or for a connection with a specified security identity (mq::securityIdentityName). If you intend to use a security identity to provide user name and password information for a connection to a secured queue manager, you can use the mqsisetdbparms command to define that identity. The name of this identity can then be referred to by the Security identity property in the MQ nodes or MQEndpoint policy, as a method of retrieving credentials for a secured connection. When you set the security identity by using this command, ensure that it is prefixed by mq::.
For example:
- Create a security identity to be used for retrieving user name and password credentials when making a connection:
```
mqsisetdbparms integrationNodeName -n mq::securityIdentityName -u username -p password
```
  For example, if you use this command to create an identity called myNodeMQCreds, you can configure the MQ node to use the credentials associated with this identity by specifying the name myNodeMQCreds in the Security identity property of the MQ node or policy.
- Configure a user name and password to be used for all MQ connections to a named queue manager (local or client connections), when no security identity name has been specified in the MQ node or policy:
```
mqsisetdbparms integrationNodeName -n mq::QMGR::QMName  -u username -p password
```
  For example, if you know that all connections to a queue manager called mySecureQM will require a user name and password, you can specify that all connections to that queue manager will use the user name and password specified by the mqsisetdbparms command:
```
mqsisetdbparms integrationNodeName -n mq::QMGR::mySecureQM  -u myUsername -p myPassword
```
- Configure a user name and password for all MQ connections (local or client connections) where no security identity name has been set on the MQ node or policy, and where the queue manager that is being connected to does not match any queue manager names that have been specified using mq::QMGR::QMName:
```
mqsisetdbparms integrationNodeName -n mq::MQ  -u username -p password
```
If no security identity has been specified, no credentials have been set for the queue manager (mq::QMGR), and no default credentials set for MQ (mq::MQ), no user name and password are passed to the queue manager, and the connection to the secured queue manager fails as a result.
Do not include the mq:: prefix when setting the security identity on the MQ node or in the MQEndpoint policy.
You can use the mqsireportdbparms to find out which security credentials have been set for the MQ connection. For example:
```
mqsireportdbparms integrationNodeName -n mq::* 
```
If you are using SSL for any MQ connections, specify the location of the key repository by using the mqsichangeproperties command.
This value is specified as the full file path of the SSL key repository minus the .kdb file extension. For example, if the SSL key repository is C:\SSL\key.kdb, set the location of the key repository by using the following command:
```
mqsichangeproperties IB10NODE -o BrokerRegistry -n mqKeyRepository -v C:\SSL\key
```
1. Ensure that the SSL key repository password stash file key repository file name.sth is located in same folder as the key repository.
  This stash file is created using WebSphere MQ GSKit.
2. Use the MQSC REFRESH SECURITY command to enable the changes to the SSL key repository to take effect.

Follow these steps to complete the required connection configuration in the MQ node or MQEndpoint policy:

Configure either a local or client connection to the queue manager, as described in one of the following topics:
- Configuring a local connection to WebSphere MQ
- Configuring a client connection to WebSphere MQ
Use the Security identity property to provide the user name and password on a specific connection to the secured queue manager, through the security identity that you created by using the mqsisetdbparms command.
The value that you set in this property is the name of the security identity that you defined by using the mqsisetdbparms command in step 1.
If you do not specify the Security identity property, the security credentials that have been set for all MQ connections (mq::MQ) or for all connections to a specified queue manager (mq::QMGR::QMName), will be used, if appropriate.

You can use the Security identity property to provide the security credentials on local and client connections. This property is not available for client connections that use a client channel definition table (CCDT); for these connections, specify the required information in the CCDT.
If you are configuring a client connection to a remote queue manager, you can choose whether to use the SSL protocol when a client connection is made to a remote queue manager.
1. Select the Use SSL property on the MQ node to provide confidentiality on the client connection, by using SSL.
  This property is available for client connections that are configured using either the MQ client connection properties or a client channel definition table (CCDT).
2. Specify the SSL peer name property, which specifies the name that is passed to the remote queue manager when making the client connection. There must be a positive match for the connection to succeed.
  This property is available only if the client connection details are specified through the MQ client connection properties; if the client connection uses a client channel definition table (CCDT), you can specify this information in the CCDT.
3. Specify the SSL cipher specification property, which specifies the name of the symmetric key cryptography algorithm through which the remote queue manager is secured.
  This property is available only if the client connection details are specified through the MQ client connection properties; if the client connection uses a client channel definition table (CCDT), you can specify this information in the CCDT.

What to do next

The MQInput node attempts to connect to the queue manager when the flow is deployed and started. The MQOutput, MQGet, and MQReply nodes attempt to connect when the first message is sent or received. If any connection problems occur, see the WebSphere MQ product documentation for information about any mqrc return code values that are reported in the IBM Integration Bus BIP messages.

If you later decide that you want to control connection properties by using an MQEndpoint policy, you can attach a policy to the message flow node. Property values that are set on the MQ Connection tab are ignored when a policy is attached to the message flow node.