In previous releases, this Connector was known as the
MQe Password Store Connector. In Tivoli® Directory
Integrator 7.1.1, it is called the JMS Password
Store Connector; its name was changed because it is now able to make
use of Tivoli Directory
Integrator'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:
This component is not available in the Tivoli Directory
Integrator 7.1.1 General
Purpose Edition.
IBM Tivoli Directory
Integrator 7.1.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.
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 Tivoli Directory
Integrator,
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 Tivoli Directory
Integrator 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.
Accumulated messages in an MQe-based Password Store are not automatically
transferred to the Tivoli Directory
Integrator. 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 Tivoli Directory
Integrator side. On the Password Store side a remote MQe
queue is configured, which points to a local MQe queue on the Tivoli Directory
Integrator side.
Messages are transferred only when both Queue Managers are operational.
When Tivoli Directory
Integrator 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 Tivoli Directory
Integrator is
running.
From security point of view, the JMS Password Store Connector can
receive messages in the following three modes as:
Plain text messages
The messages are transferred between JMS
Password Store and JMS Password Store Connector as plain text. Therefore,
no message-based security is applied.
This
feature is optional. When this option is used, a certificate from
a .jks file is used to:
Encrypt the received messages by the JMS Password Store
Decrypt the messages by the JMS Password Store Connector
Note:
Since Tivoli Directory Integrator 6.1.1 this
encryption is deprecated, because PKCS7 encapsulation offers more
secure way to transfer messages, containing encryption.
PKCS7 encapsulated messages
Starting from Tivoli Directory Integrator
6.1.1, the JMS Password Store and the JMS Password Store Connector
support PKCS7, which includes both signing and encryption.
Using PKCS7 for encapsulation is optional. By default, it is turned
off. If you want to use PKCS7, configure both JMS Password Store and
JMS Password Store Connector to use PKCS7. However, when PKCS7 is
used, the PKI encryption is not allowed, because the PKCS7 supports
encryption.
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 Tivoli Directory
Integrator.
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.
Note:
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 Tivoli Directory
Integrator.
It can be found in: TDI_install_dir\jvm\jre\bin,
where TDI_install_dir is the installed directory
of IBM Tivoli Directory
Integrator. 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: you must have chosen
the Signer Certificates list before adding the new certificate).
Note:
The implementation of PKCS7 in Tivoli Directory
Integrator 7.1.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 Tivoli Directory Integrator V7.1.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:
Open iKeyman.exe and click on Key Database File->
New...
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"
as password.
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.
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
property "pkcs7MqeConnectorCertificateAlias".
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.
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;
you can select one of the following values:
IBMMQ
IBMMQe
ActiveMQ
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 compatibility
with earlier versions.
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 compatibility with earlier versions.
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 compatibility with earlier versions.
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.
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:
This
is the default location where the MQe Configuration utility creates
the MQe initialization file.
Note:
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 Tivoli Directory
Integrator; for more information,
see "MQe Configuration Utility" in IBM Tivoli Directory Integrator V7.1.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.
Directory Integrator, Version 7.1.1