Web Event Trigger

The Web event trigger contains Java classes that encrypt an attribute (RSACipher) and publish events (SharedEventPublisher or CumulativeEventPublisher). You can integrate these classes into your Web application to build password maintenance clients. In scenarios where each message does not need to be evaluated, we recommend that you use CumulativeEventPublisher.

To store a password in a dxrUser entry, use the helper class PasswordSupport. This class ensures the integrity of the attributes userPassword, dxmPassword and dxmPwdLastChange.

Alternatively, you can use the Web event trigger to send just an event (no data change is performed). In this case, it is not necessary to read a certificate (public key) from the directory.

We provide some test clients that allow you to perform tests without a Web server environment (for example performance tests with a well defined load profile).

Note: The use of the Java classes is not restricted to Web applications; they can be used in any Java application.

A typical application of the classes in a Web application for a user password change is:

The user requests to change his password.
The user must enter the old password and enter the new password twice.
The connection to the LDAP server should change to an SSL connection, and the connection to the Web server should be HTTPS-based.
The Web application performs an authentication with the user DN and the old password to the LDAP directory.
The Web application reads the public key from the server_admin account in the configuration directory, initializes the cipher class [RSACipher.init()] and encrypts the new password [RSACipher.encrypt()].
Next, the Web application performs the necessary changes at the user entry (the prerequisite is that the user has enough access rights to change his password in the directory). It sets:
The userPassword attribute (be sure that the directory server performs a hash operation) to the new password value (use the java class PasswordSupport to store userPassword and dxmPassword).
The dxmPassword attribute to the encrypted new password value (see java class PasswordSupport).
The dxmOprTriggerOrigin attribute to a value not equal to any Active Directory domain (for example 'WebEventTrigger').
The dxmADsResetUserPassword attribute to FALSE.

all these attributes must be set in one LDAP operation to guarantee data consistency (see java class PasswordSupport).

Finally, it sends an event message to the messaging service to inform the event manager [fireEvent()].

A typical application of the classes in a Web application for an administrative password reset is:

The user requests to reset the password from the administrator (this is a process that is out of scope for DirX Identity).
The administrator authenticates to the LDAP directory with an administrative account (if he has not already done so).
The connection to the LDAP server should be a SSL connection.
The administrator searches for the user entry.
The administrator initiates a password reset. This action is an application- and customer-specific procedure that can be chosen freely (for example, the administrator clicks a Reset Password button and the default password is automatically calculated ).
The application reads the public key from the server_admin account in the configuration directory, initializes the cipher class [RSACipher.init()] and encrypts the default password [RSACipher.encrypt()].
The application next performs the necessary changes at the user entry (the prerequisite is that the administrator has enough access rights to change his password in the directory). It sets
The userPassword attribute (be sure that the directory server performs a hash operation) to the default password value.
The dxmPassword attribute to the encrypted default password value.
The dxmOprTriggerOrigin attribute to a value that is not equal to any Active Directory domain (for example, 'WebEventTrigger').
The dxmADsResetUserPassword attribute to TRUE.

all these attributes must be set in one LDAP operation to guarantee data consistency.

The application sends an event message to the message server to inform the event manager [fireEvent()].
The application sends the user an e-mail with the value of the default password.

Web Event Trigger Java Classes

Web event trigger Java classes include Java classes for encryption, event management, and message publishing. The next sections briefly describe these classes. See the Java classes documentation contained on your DirX Identity DVD for a more detailed description of these classes:

Documentation\DirXIdentity\eventing_docu.zip

Java Classes for Encryption

The RSACipher class provides RSA encryption and decryption facilities. It is initialized with an X.509 certificate or a private key [RSACipher.init()], takes a clear text parameter and encrypts it [RSACipher.encrypt()] or decrypts a byte buffer and returns a string [RSACipher.decrypt()].

For the detailed interface description, see the Java documentation "RSACipher.html" on your DirX Identity DVD. It contains a source code fragment that shows how to construct the class, read and hand over the certificate [RSACipher.init()] and encrypt some text [RSACipher.encrypt()].

Java Classes for Event Management

Two classes are provided for event management: SharedEventPublisher publishes each message. CumulativeEventPublisher sends one message per type in a given time interval.

Java Class SharedEventPublisher

This class publishes messages to the ActiveMQ message broker. The thread-safe implementation uses just one connection to the messaging service.

The Java documentation "EventPublisher.html" contains a code snippet that shows how to initialize an event publisher and send a message.

The constructor needs the topic to publish to and an initial context parameter to connect to the messaging service. The method fireEvent() takes an LDAP entry and a reason string. It writes the attributes of the LDAP entry into the "entry" field, the reason parameter into the reason field of the message and publishes it to the given topic.

This class is designed for a multi-threading environment and can be shared among several threads. It uses a separate worker thread that sends the events to the messaging service. The method fireEvent() simply delegates the operation to this worker using a backlog list. Thus it never blocks and the client application continues immediately.

For the interface documentation, see the Java documentation "SharedEventPublisher.html" on your DirX Identity DVD.

Java Class CumulativeEventPublisher

This class cumulates JMS messages using their type (for example, "passwordChanged") and publishes only ONE message within a given time interval to the messaging service. This strategy keeps message traffic and CPU consumption to a minimum. It can be applied when the event handler does not need to evaluate each message.

The method setTimerInterval() takes the timer as a long value and re-initializes it. The method fireEvent() takes an LDAP entry and a reason and publishes it to the configured messaging service.

The timer interval should be coordinated with the timer used by the event handler.

For detailed information, see the Java documentation "CumulativeEventPublisher.html" on your DirX Identity DVD.

Java Class PasswordSupport

Apart from setting userPassword and dxmPassword, PasswordSupport.storePassword calculates dxmPwdLastChange from the localtime and the ldap-server’s time. Note that these timestamps may differ, since the local machine and the server machine may be located in different time zones. Even if both machines are within the same time zone, times may be out of sync.

DxmPwdLastChange MUST be a servertime, local time would be meaningless. The calculation of the servertime from the localtime is done in several steps:

Firstly, storePassword creates a modification set comprising userPassword and the encrypted dxmPassword and modifies the respective LDAPEnty. This very entry is re-read to get the modifyTimestamp. The delta of servertime and localtime is calculated as "servertime - localtime".
Secondly, after the delta has been calculated, consecutive storePassword calls will calculate the servertime by "servertime = localtime + delta" and modify userPassword, dxmPassword AND dxmPwdLastChange in one ldap-modify operation. The entry will be re-read in order to get the modification timestamp, from which a new delta will be calculated. If this new delta differs significantly (ie 2s) from the old delta, dxmPwdLastChange will be re-written accordingly.

Jar File Deployment

Running your Web event trigger application requires the deployment of some Java classes.

Jar files to be placed in the web application (i.e. tomcat)

Folder WEBAPP/web_inf/lib:

storage:
dxcCrypto.jar Crypto functionality
dxcLogging.jar Logging
bcprov-jdk14-116.jar (encryption support)
DirXjdiscoverAPI.jar (used by storage.jar)
storage.jar (used by dxmStorage.jar, generic data storage)
dxmStorage.jar (Connectivity configuration data storage)
ldapjdk.jar (LDAP sdk)
js.jar (JavaScript from Rhino project)

misc:

crimson.jar 3rd party: XML parsing
jaxp.jar 3rd party: XML Parsing

Jars to be placed into the endorsed directory (i.e. tomcat: common/endorsed)

dxmStorageURL.jar (implements storage:// URLs)
storage.jar

Web Event Trigger Test Clients

DirX Identity provides several clients that allow you to simulate Web and WPL event trigger applications:

Data encryption client
Stress test client
WET Password Generator client using PasswordSuppport
WPL Simulator client (simulates Windows Password Listener compatible events)

The following sections describe how to configure and run these clients. Test clients are also available that simulate password changes.

The Data Encryption Client

The data encryption client simulates the change of data through an end-user Web client. It reads a definable set of entries, takes one of the attributes (if it exists), encrypts it and writes another attribute (or the same attribute). If the change is successful, it creates an event.

Configure the data encryption client with client.cfg file, then run the script runClient.bat. Configuration parameters are:

Common parameters:

trace - sets the trace details (use values between 1 and 3)
tf (or equivalently: tfile) - the trace file where the trace output will be written. If absent, no trace output will be written.

Configuration database parameters:

confdb.host - the host name where the configuration database resides
confdb.port - the port of the configuration database
confdb.user - the user to authenticate to the configuration database
confdb.password - the password
confdb.certdn - the DN of the entry that keeps the public key (the certificate) for data encryption.

Messaging service parameters:

messageServer - set the messaging service type:*
ATS* - deprecated
mq.appid - The test client’s unique identifier (required by JMS)
mq.queuename - the name of the activeMQ queue
The default value in client.cfg is domain*.dxm.event.pwd.changed*. Make sure that the domain name is included in the queue name if the flag Include Domain into topic is set at the at the domain object. Otherwise drop the prefix "domain*.*".
mq.expirationtime - the time the sent messages will expire. Default is one day (24 h).

Event body definition:

source.application - the web application name (written to dxmOprOrigin by the event manager)
source.type - the source type
source.resource - the resource, for example the AdsDomain.
source.cluster - the cluster, for example the AdsForest
source.computername - the name of the computer
source.DNSdomainname - the name of the DNSdomain
attr.username - the user name

The fields from source.resource down to attr.username can be used to distribute the messages between multiple event managers. Normally the user name is the best attribute for statistical distribution.

Data server parameters:

host - the host name of the database where the user entries reside
port - the port number
user - the user for authentication
password - the password
basedn - the base DN at which to read the entries to encrypt
searchfilter - the search filter
cleartextName - the name of the attribute from which to read the clear text. If this attribute does not exist at an entry, an event is not generated.
cyphertextName - the name of the attribute at which to write the encrypted value. Note: if this line is commented, encryption does not take place.

The Stress Test Client

The stress test client creates events for a stress test of the event server. Configure this client with the file stress.cfg and then run the script runStress.bat. The configuration parameters are:

Common parameters:

trace - sets the level of trace information (use values between 1 and 3)
tf (or equivalently: tfile) - the trace file where the trace output will be written. If absent, no trace output will be written.

Messaging service parameters:

messageServer - set the messaging service type:*
ATS* - deprecated
mq.appid - The test client’s unique identifier (required by JMS)
mq.queuename - the name of the activeMQ queue
The default value in stress.cfg is domain*.dxm.event.pwd.changed*. Make sure that the domain name is included in the queue name if the flag Include Domain into topic is set at the at the domain object. Otherwise drop the prefix "domain*.*".
mq.expirationtime - the time the sent messages expire. Default is one day (24 h).

Event body definition:

source.application - the Web application name (written to dxmOprOrigin by the event manager).
source.type - the source type.
source.resource - the resource, for example the AdsDomain.
source.cluster - the cluster, for example the AdsForest.
source.computername - the name of the computer.
source.DNSdomainname - the name of the DNSdomain.
attr.username - the user name.

Generator parameters:

cycles - the number of test cycles.
clients - the number of clients per cycle.
events - the number of events sent by a client.
sleep - the number of seconds to sleep after a cycle has been processed.

The WET Password Generator client

The WebEvent Trigger Password Generator client allows you to generate password events that are identical to events coming from the Web event trigger. Based on a definable collection of users in your user directory, this client creates random passwords either in sequence (as the search result is retrieved) or randomly. The fields in the sent message are definable. The password is written to the user entry in the directory and not part of the message.

Configure the data encryption client with password.cfg file, then run the script runPassword.bat. Configuration parameters are:

Common parameters:

trace - sets the trace details (use values between 1 and 3).
tf (or equivalently: tfile) - the trace file where the trace output will be written. If absent, no trace output will be written.

Configuration database parameters:

confdb.host - the host name where the configuration database resides.
confdb.port - the port of the configuration database.
confdb.user - the user to authenticate to the configuration database.
confdb.password - the password.
confdb.certdn - the DN of the entry that keeps the public key (the certificate) for data encryption.

Messaging service parameters:

messageServer - set the messaging service type:*
ATS* - deprecated
mq.appid - The test client’s unique identifier (required by the JMS).
mq.queuename - the name of the activeMQ queue
The default value in stress.cfg is domain*.dxm.event.pwd.changed*. Make sure that the domain name is included in the queue name if the flag Include Domain into topic is set at the at the domain object. Otherwise drop the prefix "domain*.*".
mq.expirationtime - the duration after which sent messages expire. Default is one day (24 h).
source.application - the Web application name (written to dxmOprOrigin by the event manager).

Event body definitions:

source.type - the source type.
source.resource - the resource; for example, the AdsDomain.
source.cluster - the cluster, for example the AdsForest.
source.computername - the name of the computer.
source.DNSdomainname - the name of the DNSdomain.
attr.username - the user name.

Data server parameters:

host - the host name of the database where the user entries reside.
port - the port number.
user - the user for authentication.
password - the password.
basedn - the base DN at which to read the entries to encrypt.
searchfilter - the search filter.
sizelimit - for the LDAP request.
timelimit - for the LDAP request.

Generator parameters:

random - this parameter has two modes:*
0* - during each cycle, it reads all entries from the directory that are specified in the search and generates a password change message for each of it (if it finds 100 entries, exactly 100 password change messages are created). The sequence depends on the sequence of the search result.*
>0* - during each cycle it generates this number of password changes by selecting the entries randomly from the directory.
cycles - the number of generation cycles to be performed.
sleep - the number of seconds to wait between cycles (0 means no wait time).

The WPL Simulator client

The Windows Password Listener simulator client allows you to generate password events that are identical to events coming from the Windows Password Listener. Based on a definable collection of users in your user directory, this client creates random passwords either in sequence (as the search result is retrieved) or per random. The fields in the sent message are definable. The encrypted password is always part of the message.

Configure the data encryption client with adsSimulator.cfg file, then run the script runADSSimulator.bat. Configuration parameters are:

Common parameters:

trace - sets the trace details (use values between 1 and 3).
tf (or equivalently: tfile) - the trace file where the trace output will be written. If absent, no trace output will be written.

Configuration database parameters:

confdb.host - the host name where the configuration database resides.
confdb.port - the port of the configuration database.
confdb.user - the user to authenticate to the configuration database.
confdb.password - the password.
confdb.certdn - the DN of the entry that keeps the public key (the certificate) for data encryption.

Messaging service parameters:

messageServer - set the messaging service type:
ATS - deprecated
mq.appid - the test client’s unique identifier (required by JMS).
mq.queuename - the name of the activeMQ queue
The default value in adsSimulator.cfg is domain.dxm.event.pwd.changed. Make sure that the domain name is included in the queue name if the flag Include Domain into topic is set at the domain object. Otherwise, drop the prefix "domain".
mq.expirationtime (optional) - the duration after which the sent messages expire. Default is one day (24 h).

Event body definition:

event.body - allows you to define a text file that contains a message template. This message template can contain placeholders in the form ${<user_ldap_attribute>} that are substituted during runtime.

Data server parameters:

host - the host name of the database where the user entries reside.
port - the port number.
user - the user for authentication.
password - the password.
basedn - the base DN at which to read the entries to encrypt.
searchfilter - the search filter.
sizelimit - for the LDAP request.
timelimit - for the LDAP request.

Generator parameters

random - this parameter has two modes:*
0* - during each cycle, it reads all entries from the directory that are specified in the search and generates a password change message for each of it (if it finds 100 entries, exactly 100 password change messages are created). The sequence depends on the sequence of the search result.*
>0* - during each cycle it generates this number of password changes by selecting the entries randomly from the directory.
cycles - the number of generation cycles to be performed.
sleep - the number of seconds to wait between cycles (0 means no wait time).

Password policies:

This section allows you to define password policies to assure correct password creation. These policies are currently available:

pwd.minLength - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).
pwd.maxLength - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).
pwd.minUpperChar - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).
pwd.minNumeric - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).
pwd.minNonAlphaNum - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).
pwd.minSpecialChar - For a definition, see the DirX Identity Provisioning Administration Guide (default is 0).

You can also set a suffix for the generated passwords:

pwdsuffix - Suffix for the generated passwords (the default is no suffix). For automatic testing, you can create fixed passwords together with minLength and maxLength.
Example: set both values to 4 and the suffix to 'dirx'. This action generates fixed passwords for all persons. Be sure to switch of password history in this case.