IBM TDI, Version 7.1
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 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.
- This component is not available in the TDI 7.1 General
- 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.
- 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 184.108.40.206
(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
- 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.
- 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.
The following is the JMS Password Store Connector workflow:
- 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.
- The retrieved message is verified and/or decrypted (this
step is optional).
- 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.
- This newly created Entry object is passed to the IBM TDI AssemblyLine.
On initialization, the JMS Password Store Connector performs the
- 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.
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
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.
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.
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.
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
- 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
- The private-public key pair of the Connector
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 you can follow in order to create
the required keystore/truststore .jks files.
- 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.
You will be asked to enter a password. Remember it - it has
to be provided later when setting up the components. You will need
to create at least two such files - one for the MQePasswordStore
and another one for the JMS Password Store Connector.
- 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.
- 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 you 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.
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
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:
- Open iKeyman.exe and click on Key Database File->
- 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, you will be asked to enter a password. To
keep compatibility with the other data in the example, enter "secret"
- 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
- 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.
- 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\.
- 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
- 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.
The JMS Password Store Connector constructs IBM TDI Entry objects
with the following fixed attribute structure (schema):
- Contains a single string value.
- Contains one of the following string values:
- replace (replace password values operation)
- add (add password values operation)
- delete (delete password values operation)
- A multi-valued attribute. Each value is a string representing
a password value.
- 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
There can be multiple Storage Component
servers; specify each on a separate line.
- 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;
you can select one of the following values:
- Specific Driver Attributes
- These take the form of name=value driver
attributes. For example:
- 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
- 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.
- 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).
- 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
- 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.
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:
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.
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,