JMS Password Store Connector

In previous releases, this Connector was known as the MQe Password Store Connector. In TDI 7.1, it is called the JMS Password Store Connector; its name was changed because it is now able to make use of TDI's JMS Driver pluggable architecture. This means that this connector can connect not only to the MQe Queue Manager but it can connect to the WebSphere MQ Queue Manager out of the box. In addition it can connect to any user provided Queue Manager as long as you provide the JMS Driver for establishing the connection.

The JMS Password Store Connector supports Iterator mode only.

The JMS Password Store can use PKCS7 encryption to sign and encrypt the password change notification messages before it sends them to the JMS Password Store Connector.

Notes:

1. This component is not available in the TDI 7.1 General Purpose Edition.

2. For more information about installing and configuring the IBM Password Synchronization plug-ins, please see the IBM TDI V7.1 Password Synchronization Plug-ins Guide.

3. IBM TDI 7.1 components can be deployed to take advantage of MQe Mini-Certificate authenticated access. To use these MQe features, it is necessary to download and install IBM WebSphere MQ Everyplace 2.0.1.7 (or higher) and IBM WebSphere MQ Everyplace Server Support ES06. Use of certificate authenticated access prevents an anonymous MQe client Queue Manager or applications submitting a change password request to the JMS Password Store Connector.

4. IBM MQ Everyplace does not support IP Version 6 addressing; as a consequence, the JMS Password Store Connector can only reach MQe using traditional IPv4 addresses.

5. IBM MQ Everyplace is deprecated in this version of TDI, and will be removed in a future version. A suitable lightweight message queue will be provided at that time.

The JMS Password Store Connector supports receiving messages from multiple password stores.

Connector Workflow

The following is the JMS Password Store Connector workflow:

1. The JMS Password Store Connector requests a message from a predefined queue on either its local MQe Queue Manager (if using the MQe JMS Driver) or the external Queue Manager (if using any other than the MQe JMS Driver). The messages are retrieved using the JMS interface.

2. The retrieved message is verified and/or decrypted (this step is optional).

3. The message is parsed and an Entry object is created. The attributes of this Entry object represent the user ID, the password values and the type of password update.

4. This newly created Entry object is passed to the IBM TDI AssemblyLine.

On initialization, the JMS Password Store Connector performs the following actions:

Using the MQe JMS Driver:

• The Connector starts the MQe Queue Manager if it is not already started and gets a reference to the running Queue Manager.

• Initiates a connection to the Storage Component and notifies the Storage Component that the JMS Password Store Connector Queue Manager is up and ready for receiving notifications.

Using other than the MQe JMS Driver:

The specific JMS Driver is initialized and a connection is established with the external Queue Manager.

On getting a password update message, the Connector can operate in one of three modes:

No wait

Checks if password update message is available in the QueueManager queue. If yes, the mode retrieves and parses the message. If no, the mode returns NULL, signalling the end of the Iterator.

Number of milliseconds to wait

Waits for a specified number of milliseconds for a password update message to appear in the QueueManager queue. If the password update message appears, this mode retrieves and parses the message. If not, this mode returns NULL, signaling the end of the Iterator.

Wait forever

The Connector waits until a password update message appears in the QueueManager queue. It never returns NULL, and when operating in this mode it must be stopped externally.

By default, the Connector automatically acknowledges every message it receives from the QueueManager JMS queue. However, you can change this behavior by de-selecting the Auto Acknowledge parameter; in that case, you are responsible for message acknowledgements yourself by calling the Connector's acknowledge() method at appropriate places in the AssemblyLine. Each time you call the Connector's acknowledge() method you acknowledge all messages delivered so far by the Connector.

Force transfer of accumulated messages from the JMS Password Store with MQe

Accumulated messages in an MQe-based Password Store are not automatically transferred to the TDI. To force transmission of such accumulated messages, use the Storage notification server(s) parameter of the JMS Password Store Connector and the "mqe.notify.port" parameter of the JMS Password Store.

Here is an explanation:

When the JMS Password Store is used with MQe, there are two MQe Queue Managers involved - one on the Password Store side and the other on the TDI side. On the Password Store side a remote MQe queue is configured, which points to a local MQe queue on the TDI side.

Messages are transferred only when both Queue Managers are operational. When TDI is not running, the Queue Manager of the Password Store accumulates arriving messages. Normally MQe does not automatically detect when a remote Queue Manager goes operational. So when the Directory Integrator goes back online, the accumulated messages are not transferred until a new message arrives in the Password Store.

There is a special feature which allows the JMS Password Store Connector to "pull" accumulated messages from the Password Store. This feature is configured by the Storage notification server(s) parameter of the Connector and the "mqe.notify.port" parameter of the JMS Password Store. When the Connector initializes, it sends a notification to the Password Store to start sending accumulated messages. Note that currently there is no "push" alternative, that is, the Password Store does not periodically check if TDI is running.

PKCS7 Encryption support

The JMS Password Store can use PKCS7 encryption to sign and encrypt the password change notification messages before it sends them to the JMS Password Store Connector. The use of PKCS7 encapsulation is optional; by default it is turned off. Both signing and encryption need certificates in order to function. Usage of PKCS7 is incompatible with the older PKI-based encryption mechanisms available in older versions of TDI.

With the PKCS7 option activated, it verifies the signature of each received message by comparing the Signer certificate with those in its trust store. In case of a match it verifies the message signature. If the signature verification is successful the Connector accepts the message and decrypts it with the Connector's private key from its own certificate.

If PKCS7 needs to be used then both the JMS Password Store Connector and the JMS Password Store (all of them, if multiple Stores are used) need to be setup to use PKCS7. If only one side is configured to use PKCS7 then an error will occur.

The certificates are stored in a .jks file. The Connector has a .jks file and the JMS Password Store has another .jks file.

Signing of messages

Signing is used to verify that the sender of the message is the one he/she claims to be.

In this particular scenario the JMS Password Store Connector needs to verify that the sender of a password change notification message is actually a trusted JMS Password Store.

It is possible to have several password stores sending messages to a single JMS Password Store Connector. In this case the Connector must be configured so that its .jks file contains the public keys of each of the trusted password stores.

Encryption of messages

Encryption is achieved by having the password store use the public key of the Connector to encrypt the message. Then the Connector uses its private key to decrypt the message.

Certificate management

A .jks file is required in order to be able to work with the PKCS7 functionality. It must contain not only the JMS Password Store Connector's certificate, but also the certificates of all the password stores that send messages to it.

The JMS Password Store Connector's certificate is a self-signed personal certificate, whose private key is used to decrypt the messages from the password store.

The password stores' certificates are trusted signer certificates, which are supplied from each JMS Password Store's .jks file. Every received message is then verified: the public key, attached to it, is compared with the available in the .jks file. In case of a match the message signature is verified against the certificate and then the message is decrypted using the Connector's own private key.

Certificate structure

Certificates are stored in a .jks file. The Connector has a .jks file and the password store has another, corresponding, .jks file. The two .jks files need to contain the following so that PKCS7 can be used:

JMS Password Store .jks file

• The public key of the Connector as a trusted signer certificate

• The private-public key pair of the password store

JMS Password Store Connector .jks file

• The public key of each trusted password store as a trusted signer certificate

• The private-public key pair of the Connector

Creating certificates

The primary tool used to handle .jks files is ikeyman.exe. Ikeyman.exe is a tool available with every JVM distributed with TDI.

It can be found in: TDI_install_dir\jvm\jre\bin, where TDI_install_dir is the installed directory of IBM TDI. Below are the steps we can follow in order to create the required keystore/truststore .jks files.

1. Creating a .jks file

   To create a new .jks file click on Key Database File -> New and choose JKS together with the desired name and file path. We will be asked to enter a password. Remember it - it has to be provided later when setting up the components. We will need to create at least two such files - one for the MQePasswordStore and another one for the JMS Password Store Connector.

2. Creating a certificate

   To create a new certificate click on the drop-down menu above the list of certificates and choose Personal Certificates. Next, click on New Self-Signed... and enter the appropriate information.

3. Transferring certificates

   The last step is adding the just created self-signed certificates from the MQePasswordStore's JKS to the JMS Password Store Connector's and vice versa. For this purpose we have to extract the certificate as DER binary data: click on Extract Certificate... and then choose Data Type -> DER Binary data. Save it to an appropriate location with the desired name and open the other .jks file. Click Add... and find the file with the DER extracted data (Note: have chosen the Signer Certificates list before adding the new certificate).

The implementation of PKCS7 in TDI 7.1 does not support certificates that are secured with an additional password except the one set for the .jks file.

Example usage

The following example demonstrates how the JMS Password Store Connector can be configured to work with the configured JMS Password Store, described in IBM TDI V7.1 Password Synchronization Plug-ins Guide. Parameter PKCS7 is checked - meaning that the PKCS7 encryption/certification option is enabled.

The path to the .jks file, parameter PKCS7 Key Store File is C:\dev\di611_061025a\certs\mqeconnpkcs7.jks. It must contain its self-signed certificate as well as the trusted signer certificate of the JMS Password Store (please refer to Creating certificates for more information about creating the necessary certificates). In our case the parameter MQeConnector Certificate Alias is specified as "mqeconn".

For the needs of our example we need to create the two .jks files - 'mqepkcs7.jks' and 'mqeconnpkcs7.jks'. The steps are as follows:

1. Open iKeyman.exe and click on Key Database File-> New...

2. Select the desired location of the file. For the example described above, save the .jks file under C:\dev\061025a\certs with the name mqeconnpkcs7.jks. By pressing the OK button, we will be asked to enter a password. To keep compatibility with the other data in the example, enter "secret" as password.

3. The next step is to create the JMS Password Store Connector's certificate itself. For this purpose select Personal Certificates from the drop-down menu and click New Self-Signed... The Key Label is the alias of the certificate in the .jks file. Set it to "mqeconn". The other options can be left with the default values.

4. Extract the just created self-signed certificate "mqeconn" as DER data in the same folder: C:\dev\di611_061025a\certs. Choose a name that corresponds to the certificate itself (for example, mqeconn). This file will be used later to import the JMS Password Store Connector's certificate in the .jks file of a JMS Password Store.

5. Repeat the steps from 1 to 4, but this time the location of the .jks file is: C:\Program Files\IBM\DiPlugins\mqepkcs7.jks and the password again: "secret". For Key Label of the JMS Password Store certificate set the value to "mqestore" and extract it as mqestore.der in the same directory: C:\Program Files\IBM\DiPlugins\.

6. Both created .jks files must exchange their certificates. Since the mqepkcs7.jks file is opened, import first the DER binary data that was extracted from mqeconnpkcs7.jks. Select Signer Certificates from the drop-down list and click on Add... In the window that popped up select "Binary DER data" as Data type and then browse to the location C:\dev\di611_061025a\certs, where the .der file is saved. Select the mqeconn.der file and click "OK". A label for the imported certificate is required. To avoid confusion it is advisable to give it the same alias as in the other .jks file, in this case, mqeconn, because this value must be given in the properties file of the JMS Password Store for the property "pkcs7MqeConnectorCertificateAlias".

7. The same procedure must be performed on the mqeconnpkcs7.jks file (the key store holding the necessary certificates for the connector). First open the .jks file by clicking Key Database File-> Open... and navigating to the exact location. If you followed all the instructions precisely the path to the required file should be C:\dev\di611_061025a\certs. The password will be prompted for again. Afterwards repeat step 6 with the new parameters. The location is C:\Program Files\IBM\DiPlugins and the certificate name is mqestore.der. For convenience name it "mqestore" again. With this step the example is completed.

Schema

The JMS Password Store Connector constructs IBM TDI Entry objects with the following fixed attribute structure (schema):

UserID

Contains a single string value.

UpdateTypes

Contains one of the following string values:

• replace (replace password values operation)

• add (add password values operation)

• delete (delete password values operation)

Passwords

A multi-valued attribute. Each value is a string representing a password value.

Configuration

GetNext Timeout

Specify the number of milliseconds the Connector waits for a new password update message to appear in the QueueManager queue. Specify -1 to wait forever, and 0 to return immediately if no message is available (returning NULL).

Storage notification server(s)

Specify in a host:port format the Storage Component server that listens for notifications from the JMS Password Store Connector. The default value for the port is 41002 and the host must be the IP address of the machine where the Password Synchronizer and the Storage Component are deployed.

There can be multiple Storage Component servers; specify each on a separate line.

Broker

The URL for the JMS server. When working with IPv6 addresses, this parameter must contain both the IPv6 JMS Server address as well as the JMS Server port. This parameter can also be used for providing the MQe initialization file.

JMS Server Type

The full name of the class implementing the JMS Driver interface; we can select one of the following values:

• IBMMQ

• IBMMQe

Specific Driver Attributes

These take the form of name=value driver attributes. For example:

QUEUE_FACTORY_NAME=primaryQCF, or
TOPIC_FACTORY_NAME=primaryTCF

Server Channel

The name of the channel configured for the MQ server. This parameter only applies when the JMS Password Connector is used with IBM WebSphere MQ Server. This parameter is left in the configuration for backward compatibility

Queue Manager

The name of Queue Manager defined for MQ server or INITIAL_CONTEXT_FACTORY for non-IBM MQ.

User Name

The User name for authenticating access to the JMS.

Password

The Password for authenticating access to the JMS.

Client ID

The client ID to use for Queue connections.

Use SSL Connection

Enables the use of parameters and configuration settings required for SSL connection.

SSL Server Channel

The name of channel configured for using SSL to access the MQ server. This parameter only applies when the JMS Connector is used with IBM WebSphere MQ Server. This parameter is left in the configuration for backward compatibility.

SSL CipherSuite

The Cipher Suite name which corresponds to the cipher selected in configuring MQ server channel. This parameter only applies when the Connector is used with IBM WebSphere MQ Server. This parameter is left in the configuration for backward compatibility.

Auto Acknowledge

If checked each message is automatically acknowledged, otherwise messages should be acknowledged manually through the Connector's acknowledge() method. Default is selected.

Decrypt messages

Check this field if the Storage Component encrypts the password update messages and they need to be decrypted by the Connector.

Key Store File

The path of the JKS file used to decrypt password data (only taken into account when the Decrypt messages field is selected).

Key Store File Password

The password of the JKS file (only taken into account when the Decrypt messages field is selected).

Key Store Certificate Alias

The alias of the key from JKS file (only taken into account when the Decrypt messages field is selected).

Key Store Certificate Password

The password used to retrieve the private key. If not specified, the Key Store File Password is used to retrieve the private key (only taken into account when the Decrypt messages field is selected).

PKCS7

This indicates whether PKCS7 encapsulation is used or not. The default value is disabled. All other parameters related to the PKCS7 functionality are considered if only this parameter is enabled.

PKCS7 Key Store File

This is the full path to the JMS Password Store Connector's JKS together with its name. There is no need for double slash "\\" instead of single "\", when specifying the file path on Windows platforms.

PKCS7 Key Store File Password

The actual, plaintext value of the password for the JKS file (whereas for the MQePasswordStore's property the encrypted version is required).

MQeConnector Certificate Alias

The alias of the JMS Password Store Connector's certificate as it is saved in the .jks file without any extensions.

Detailed Log

Check this field for more detailed log messages.

JMS drivers

IBM WebSphere MQe driver

In order to use MQe as the JMS provider for the JMS Password Store Connector, the JMS Server Type config parameter must be set to "IBMMQE", and the "systemqueue.jmsdriver.name" property in global.properties or solution.properties must be set to "com.ibm.di.systemqueue.driver.IBMMQe".

The IBM WebSphere MQe driver has one parameter:

• mqe.file.ini - the value of this parameter must be the absolute filename of the MQe initialization file.

For example, if the JMS Password Store Connector needs to be configured to use MQe, then the following line must be put in global.properties or solution.properties:

systemqueue.jmsdriver.param.mqe.file.ini=TDI_install_folder/MQePWStore/pwstore_server.ini

This is the default location where the MQe Configuration utility creates the MQe initialization file.

In order to be able to use MQe as the JMS provider for the JMS Password Store Connector an MQe Queue Manager needs to be created. This can be done using the MQe Configuration utility bundled with TDI; for more information, see "MQe Configuration Utility" in IBM TDI V7.1 Installation and Administrator Guide.

IBM WebSphere MQ driver

In order to use IBM WebSphere MQ as the JMS provider for the JMS Password Store Connector the JMS Server Type config parameter must be set to "IBMMQ".

The IBM WebSphere MQ driver has the following parameters:

• Broker (jms.broker) - the MQ server address (IP address and TCP port number); an example value would be "192.168.113.54:1414"

• Server Channel (jms.serverChannel) - the name of the server channel configured for the MQ server instance.

• Queue Manager (jms.qManager) - the name of the Queue Manager defined for the MQ server instance.

• SSL Cipher Suite (jms.sslCipher) - the cipher suite name which corresponds to the cipher selected when configuring the MQ server channel; an example value would be "SSL_RSA_WITH_RC4128_MD5".

• Use SSL Connection (jms.sslUseFlag) - specifies whether SSL will be used on the connection to the MQ Server instance; valid values are true and false.

For specific configuration of the Websphere MQ server, please refer to its documentation.

See also

System Queue Connector,
The chapter on System Queue in the IBM TDI V7.1 Installation and Administrator Guide,
JMS Password Store in IBM TDI V7.1 Password Synchronization Plug-ins Guide,
JMS Connector.