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 and Creating a Data Model

The files within the directory dsml2testservice define a data representation for this example.  Three files are included:
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
  1. Copy the directory dsml2testservice and its contents from the examples folder to the location ${TIM_HOME}\data\remote_resources.
  2. Bring up a command line interface and change directories to the {$ITIM_HOME}\bin\win.
  3. Execute the command config_remote_services -profile dsml2testservice.
  4. 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:
  1. 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.
    Form Design of Account Entity

    Figure 1 Form Design of Account Entity


    Form Design of Service 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

  2. Navigate to Provisioning | Service Management.
  3. Add a new service of type dsml2testservice.
  4. 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.

  5. Create a provisioning policy for the new service.
A screen shot of the service form is shown in Figure 3.


Screen Shot of DSML2TestService Detail Form

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:
  1. Add a naming context called dc=ibm
  2. 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.
  3. Add an example inetOrgPerson under the newly created organizational unit.  Filling in the following attribute values:

Screenshot of LDAP Service Directory Tree

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:
  1. 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

  2. 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

  3. 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

  4. 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

  5. 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.
  6. 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.
  7. 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.


Screenshot of test service account form


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


Screenshot of Provisioned LDAP Account

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:
  1. In the PersonAdd tab change the mode from Add Only to Update.
  2. 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.
  3. In the Event Handler Configuration tab set the Assembly Line for Modify to processAdd.
  4. Restart the Event Handler.
  5. 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:
  1. Add a new Assembly Line and call it processDelete.
  2. 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.  
  3. In the configuration tab of the connector set the configuration details to be the same as the connector in the processAdd assembly line.
  4. In the Link Criteria tab add a new Link Criteria, building the link criteria with the same custom script described above for modify requests.
  5. Stop the event listener, if it is still running, and close the event handler tab if it is still open.
  6. Open the event handler tab again and in the Configuration panel set the Assembly Line for Delete to processDelete.
  7. Restart the Event Handler.
  8. 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.

Screenshot of Group Selection in TIM User Interface

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:

  1. 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'.
  2. 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.