Example: Using IDI as a TIM End-Point to Manage Accounts
Contents
Part (a)Provisioning an Account
Defining and Creating a Data Model
Configuring TIM
Configuring the LDAP Server
Configuring IDI
Running the Test
Part (b) Other Account Management Operations
Part (c) Group Support
Enabling SSL between TIM and IDI
Enabling two-way SSL between TIM and IDI
Authentication
Filtering of Search Requests
Part (a) Provisioning an Account
This example will use IDI with a connector to an LDAP server to manage accounts
in the same way as a TIM end point. TIM will be acting as a DSMLv2 client
and IDI will be acting as a DSMLv2 Server. There are steps to complete
this part of the example are:
- defining a data model and adding it to the TIM data store
- configuring TIM for management of of the newly defined account type
- configuring an LDAP server to store the example accounts
- configuring IDI event handler and assembly line to accept account management
requests
- running tests to provision, modify, and delete accounts
Defining and Creating a Data Model
The files within the directory dsml2testservice define a data representation
for this example. Three files are included:
- schema.dsml defines the directory syntax for the account and service
classes.
- resource.def is the resource definition for the creation of a service
profile
- CustomLabels.properties defines labels for the forms displayed in the
user interface
The schema.dsml file contains the definitions of LDAP attributes and object
classes for the account, service, and a group object in DSML format. These
are described in Table 1.
Table 1 Entities Defined for Data Model
Entity Type
|
Object Class
|
Description
|
Service
|
erdsml2testservice
|
This represents a service in TIM to manage remote
LDAP accounts.
|
Account
|
erdsml2testaccount
|
This represents account entries associated with the
service of type erdsml2testservice. |
Supporting Data
|
erdsml2testgroup
|
This represents the type of a group that account users
may have membership to.
|
The attributes associated with the service are described in Table 2. The
labels are given in CustomLabels.properties.
Table 2 Definition of Test Service Attributes
Attribute Name
|
Label
|
Required
|
Description
|
erservicename
|
Service Name
|
Yes
|
The name of the service to display on the TIM user
interface.
|
erurl
|
URL
|
Yes |
The URL that IDI is listening on.
|
eruid
|
User ID
|
Yes |
The principal used for authentication of TIM by IDI.
|
erpassword
|
Password
|
Yes |
The password used for authentication of TIM by IDI. |
The attributes associated with the account are described in Table 3.
Table 3 Definition of Test Account Attributes
Attribute Name |
Label |
Required |
Description |
eruid
|
User ID
|
Yes |
The identifier that the account user is identified
by.
|
erpassword
|
Password
|
Yes |
The password that the managed resource authenticates
its users by.
|
cn
|
Full Name
|
Yes |
The full name of the user.
|
lastname
|
Last Name
|
Yes |
The family name of the user.
|
firstname
|
First Name
|
No
|
The given name of the user. |
telephoneNumber
|
Telephone Number
|
No |
The telephone number of the user. |
mail
|
Email
|
No |
The email address of the user. |
testgroupmembership
|
Test Group
|
No
|
Membership in Test Groups.
|
The group has a single attribute, erdsml2testgroup, used to identify the
group and display in the user interface..
The service and accounts profiles are defined in the resource definition file,
resource.def. This file also contains an attribute for the factory for
handling the protocol, as well as a list of service properties to send with
requests.
To load the data definitions into TIM follow these steps (listed for Windows
2000 but use equivalent steps for UNIX):
NOTE: you will need to source the DB2 environment when doing this on UNIX systems. E.G.: . /home/db2inst1/sqllib/db2profile
- Copy the directory dsml2testservice and its contents from
the examples folder to the location ${TIM_HOME}\data\remote_resources.
- Bring up a command line interface and change directories to the {$ITIM_HOME}\bin\win.
- Execute the command config_remote_services -profile dsml2testservice.
- Restart the TIM server.
You may verify that the LDAP schema has been imported successfully by using
the directory administration console. Any errors that occur will appear
in the TIM log and also the directory log if they are related to schema import
problems.
Configuring TIM
To add and configure the service instance follow these steps in the TIM user
interface:
- Customize the account and service forms. Without customization
the service form displayed will include some attributes that should be hidden
and the attributes that should be displayed are not listed in a logical order.
This can was corrected with the form designer, however. The form
designer for account and service entities is shown in Figures 1 and 2.
Figure 1 Form Design of Account Entity
Figure 2 Form Design of Service Entity
Notice the listbox widget used for the testgroupmembership attribute.
This uses a search to allow users to search for group data brought back
during reconciliation. To configure the search, double click on the widget
in the designer and enter these values for in the dialog:
Parameter |
Value |
Explanation |
Search Base
|
Contextual |
Relative to the Service |
Attribute
|
dsml2groupname
|
Name of the attribute to display |
Filter |
(objectclass=erdsml2testgroup) |
How to narrow the values to select from. |
Multiple Value
|
checked
|
The use may add more than one value
|
- Navigate to Provisioning | Service Management.
- Add a new service of type dsml2testservice.
- Add the following values for the test service parameters
Parameter
|
Value
|
Explanation |
Service Name |
dsml2 test |
A value to display on the TIM user interface.
|
URL |
http://localhost:8800 |
This is needed to locate IDI.
|
User ID |
agent |
The principal used for TIM to authenticate to IDI. |
Password |
agent |
The password used for TIM to authenticate to IDI. |
Naming Context
|
dc=ldap
|
Used to relate requests to the correct context within
IDI.
|
Category
|
Account
|
Type of entity for use with TIM data services API's.
This is the appropriate value for account management.
|
- Create a provisioning policy for the new service.
A screen shot of the service form is shown in Figure 3.
Figure 3 Screen Shot of Custom Service Instance Detail Form
Configuring the LDAP Server
The managed resource in this example will be the same directory server as
TIM uses as it's data store. The 'accounts' added will be inetorgperson entries
added in a place in the directory tree that we will create now. However,
the same principals are equally applicable to other resources and account
types.
To configure an LDAP Server to store account data perform these steps:
- Add a naming context called dc=ibm
- Under that naming context add an organizational unit called ou=white
pages. A screenshot of the LDAP server directory tree is shown in Figure
4, which shows the location of the ou=whitepages,dc=ibm branch.
- Add an example inetOrgPerson under the newly created organizational
unit. Filling in the following attribute values:
- dn: uid=dtrump,ou=white pages,dc=ibm
- cn: donald trump
- sn: trump
- givenname: donald
- mail: dtrump@trumptower.com
- telephoneNumber: 123/456-789
- uid: dtrump
Figure 4 Screenshot of LDAP Service Directory Tree
Configuring IDI
An example IDI configuration file called 'account_management.xml' is provided.
The reader may use that and make adjustments or follow the steps outlined
here.
To configure IDI for account management perform these steps:
- Add an assembly line. The name of the assembly line should be
processAdd. In the Call/Return tab of the assembly line add the names
of the attributes defined in the schema.dsml file as Work Entry attributes.
Unselect the required checkbox on all of the attributes. A screenshot
with this configured is shown in Figure 5.

Figure 5 Configuration of External Attributes in
Assembly Line Call/Return Screen
- Add a Connector to the assembly line. The connector should be
of type ibmdi.JNDI, called PersonAdd, and be in add only mode. A screen
shot is shown in Figure 6. In the configuration tab, enter these values
Parameter
|
Value
|
JNDI Driver
|
com.sun.jndi.ldap.LdapCtxFactory
|
Provider URL
|
<url of directory server>
|
Referrals
|
Follow
|
Authentication Method
|
Simple
|
Login Name
|
<your login name>
|
Login Password
|
<your password>
|
Name Parameter
|
$dn
|
Search Base
|
ou=white pages, dc=ibm
|
Search Scope
|
Subtree
|

Figure 6 Screenshot of JNDI Connector
- In the Output tab of the connector click the Connect toolbar icon and then
click the next toolbar icon. This will allow IDI to determine the
schema of the output source. A list of available attributes will
be listed as shown in Figure 7.

Figure 7 Screenshot of Schema Introspection by
JNDI Connector
- In the Output Map tab of the connector add the values below. The
dn needs to remove the leading "er" from the attribute name "eruid" and append
the base distinguished name. A screen shot of the panel is shown in
Figure 8.
Connector Attribute
|
Mapping
|
$dn
|
var incomingDN = work.getString("$dn"); var end = incomingDN.indexOf(","); var outgoingDN = incomingDN.substring(2, end) + "," + PersonAdd.getConnectorParam("ldapSearchBase"); ret.value = outgoingDN;
|
cn
|
cn
|
givenname
|
firstname
|
mail
|
mail
|
objectclass
|
ret.value="inetorgperson";
|
sn
|
lastname
|
telephoneNumber
|
telephoneNumber |
uid |
eruid |
userpassword
|
erpassword
|
- Add an event hander of type ibmdi.DSMLv2EventHandler named TIM Listener.
In the configuration screen set the port to 8800 and the assembly line
to add to Assembly Lines/processAdd.
- The userpassword / erpassword attribute is a binary attribute. It is
base 64 encoded by TIM for transmission in the XML document to IDI and then
decoded by IDI to transform it back into a byte array. To configure the event handler
to perform this decoding add erPassword to the Binary Attributes list in the configuration
screen for the handler.
- Click the run button on the Event Handler.

Figure 8 Screenshot of Output Map in IDI JNDI Connector
Running the Test
To run the example, in the TIM user interface navigate to a person, go to
manage accounts, and select provision new. Select dsml2testaccount.
Fill in the form with values and submit. The account detail for
is displayed in Figure 9.
Figure 9 Screenshot of DSMLv2 Test Service Account
Form
There are no groups available to select from at this stage because we haven't
reconciled them into TIM yet.
After several seconds, after refreshing the list of accounts in the user's
Account Management Screen, the new account should appear, as shown in Figure
10. If the IDI console is running in verbose mode then a message should
be displayed in the main console. An entry should be present in the
directory server, under the branch ou=white pages, dc=ibm, as shown in Figure
11.
Figure 10 The TIM Account List after Submitting the
Provisioning Request
Figure 11 Screenshot of Provisioned LDAP Account
Part (b) Modify and Delete Account Management Operations
To configure IDI to handle modify operations follow these steps in the ibmditk
user interface:
- In the PersonAdd tab change the mode from Add Only to Update.
- In the Link Criteria tab add a new Link Criteria, building the link
criteria with the custom script:
var dn = work.getString("$dn");
var end = dn.indexOf(",");
var filter = dn.substring(2, end);
ret.filter = filter;
This is required to strip the first two characters "er" from the user
id attribute.
- In the Event Handler Configuration tab set the Assembly Line for Modify
to processAdd.
- Restart the Event Handler.
- In the TIM user interface test the change by submitting a change to
the account created in the first part of the example.
Suspend, restore, and change password requests are handled as modify requests.
To configure IDI to handle delete operations follow these steps in the ibmditk
user interface:
- Add a new Assembly Line and call it processDelete.
- Add a new connector to the processDelete assembly line, set it to be
of type ibmdi.JNDI, and set it to operate in Delete mode.
- In the configuration tab of the connector set the configuration details
to be the same as the connector in the processAdd assembly line.
- In the Link Criteria tab add a new Link Criteria, building the
link criteria with the same custom script described above for modify requests.
- Stop the event listener, if it is still running, and close the event
handler tab if it is still open.
- Open the event handler tab again and in the Configuration panel set
the Assembly Line for Delete to processDelete.
- Restart the Event Handler.
- In the TIM user interface test the change by submitting a delete request
for the account created in the first part of the example.
Search requests are configured as per the instructions in Example 1 for Identity
Feed.
Part (c) Reconciliation and Group Support
For group support the group data should be pulled into TIM with a reconciliation.
To do this create a new assembly line for processing search requests.
The assembly line will consist of three connectors as described in
Table 4 and shown in Figure 12.
Table 4 Connectors used in Search Assembly Line
Connector Name
|
Type
|
Mode
|
Description
|
AccountConnector
|
LDAP
|
iterator
|
Returns all the account entries.
|
GroupMembersipLookup
|
LDAP |
lookup
|
Finds membership relations between the accounts and
groups.
|
GroupConnector
|
LDAP |
iterator |
Returns all the group entries. |

Figure 12 Screenshot of Assembly Line with Account
and Group Search
Bringing group data into TIM and maintaining the membership relations to accounts
is a challenge because of the different way that group membership is viewed
in LDAP. In LDAP we are using the groupOfNames object class to represent
groups. This contains a multi-valued attribute member, which represents
a list of members. On the other hand, in TIM group membership is represented
as an attribute on the account entry, the value of which is the distinguished
name of the group. Therefore, at some point in the search process we
need to discover the membership relations and add them to the account entries,
which is the intention of the lookup in the GroupMembershipLookup connector.
The GroupMembershipLookup connector contains a link criteria linking the member
attribute of the group object to the distinguished name of the account:
ret.filter = "member=uid=" + work.getString("eruid") + " ," + AccountConnector.getConnectorParam("ldapSearchBase");
This linking rule states that a member attribute of the group must match the
distinguished name of the person entry.
Secondly, we need to define an input map, adding the group name to the current
work entry. Thirdly, we need to add a hook to the lookup successful
event with this script:
work.addAttributeValue("testgroupmember", work.getString("groupDn"));
This is to add an attribute value to the account work entry found in the
previous connector.
To add an example group that can be reconciled back to TIM, use the directory
console to add this entry under ou=whitepages, dc=ibm:
Item
|
Value
|
objectclass
|
groupOfNames
|
Relative DN
|
cn=salesperson
|
cn |
salesperson
|
member
|
uid=dtrump, ou=white pages, dc=ibm
|
The groupOfNames objectclass has required attributes cn and member.
After reconciliation of group data, users may now select groups in the TIM
account management user interface as shown in Figure 13.

Figure 13 Screenshot of Group Selection in TIM Account Management User
Interface
To be able to process the modify request to add the person to the group on
the managed resource, we have to modify the processAdd assembly line.
Enabling SSL between TIM and IDI
This part of the example will configure TIM and IDI to communicate with Hypertext
Transfer Protocol over a Secure Sockets Layer (https). The DSMLv2 ServiceProvider
implmentation in TIM uses an IBM implementation of the the Java Secure Sockets
Extension (JSSE) interface from Sun. Configuration of https mainly involves
setting system parameters to configure JSSE and making certificates available.
IDI acts as the SSL server when TIM is initiating connections. TIM
acts as the SSL server when IDI initiates a connection. Therefore,
both server and trust files are required on both TIM and IDI. The certificate
stores used by these interfaces and implementations uses the Java Key Store
(JKS) format. This example will use IBM's IKeyMan certificate management
tool. Sun's keytool provided with their JDK can equally well be used
but is not as user friendly.
Steps for enabling SSL
1. Create Java key store (JKS) format files using the Websphere IKeyMan key
management tool for both the server and the client.
2. To enable IDI to act as the SSL server, check the 'Use SSL' checkbox in
the
HTTP Event Handler configuration tab. Follow the instructions in the
IDI Reference Guide 'IBM Directory Integrator Secure Sockets Layer Support'.
Restart IDI. Make sure that the trust database and key database properties
are
pointing to the JKS files in step 1.
3. To enable TIM to recognize the 'https' protocol in the URL when making
a
request to IDI, add the property
java.protocol.handler.pkgs=com.ibm.net.ssl.internal.www.protocol
in the JVM settings using the Websphere console. This can be found
under Application Servers > server1 > Process Definition > Java
Virtual Machine > Custom Properties.
4. To enable TIM to be a client of the SSL connection with IDI add the
following properties
javax.net.ssl.trustStore=<full path to trust store>
javax.net.ssl.trustStorePassword=<password to trust store>
in the JVM settings using the Websphere console (same place as the URL protocol
handler).
5. Save the settings and restart Websphere.
Enabling two-way SSL between TIM and IDI
TIM and IDI can additionally be configured to support two-way, or mutual, SSL
authentication. With two-way SSL, the end-point acting as the server also
authenticates the client. The steps for configuring two-way SSL are essentially
the same as those listed in the previous section, with the following additions:
1) Enable TIM to be the server of an SSL connection by adding the properties:
javax.net.ssl.keyStore=<full path to key store>
javax.net.ssl.keyStorePassword=<password to key store>
in the JVM settings using the Websphere console. This can be found under
Application Servers > server1 > Process Definition > Java Virtual Machine >
Custom Properties.
2) Enable two-way SSL in IDI by checking the 'Use two-way SSL' checkbox in the
Event Handler configuration tab.
Detailed step-by-step instructions for setting up and testing two-way SSL
between TIM and IDI are available here.
Authentication of TIM to IDI
Authentication of incoming DSMLv2 requests is configured by setting the authorization
connector in the DSMLv2 event handler configuration panel. This should
be configured to look up the username attribute from a credentials data store.
A BTree database file credentials store is provided with this example.
It is named 'credentials.db'. The values of the username and password
in the datastore are 'agent' and 'agent'. To configure it follow these
steps:
- Create a new IDI Connector of type BTreeObjectDB in lookup mode. Set
the File Name to be credentials.db. Set the Key Value Attribute to be
'username'.
- In the DSMLv2 event handler set the Auth Connector to be the Connector
created in step 1.
Filtering of Search Requests
The reconciliation management user interface for TIM allows the user to enter
a search filter for each reconciliation unit. This filter is passed
to IDI, however, within IDI configuration is required to make use of the
filter. The connector must be customized using a script to read the
filter from the incoming request and set it into the search filter attribute
for the LDAP connector.
To make use of this feature in this example, in the TIM reconciliation user
interface, set a query for the reconciliation unit of (uid=dtrump). Notice
that the filter applies to the attributes as interpreted within the IDI connector.
In the IDI processSearch assembly line, in the Hooks tab for the AccountConnector,
add this script in the Before Selection Hook:
AccountConnector.connector.setParam("ldapSearchFilter", work.getString("dsml.filter"));
Perform a reconciliation and check that only the user dtrump was returned.