LDAP Connector

IBM Tivoli Directory Integrator

LDAP Connector

The LDAP Connector provides access to a variety of LDAP-based systems. The Connector supports both LDAP version 2 and 3. It is built layered on top of JNDI connectivity.

This Connector can be used in conjunction with the IBM Password Synchronization plug-ins. 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.

Note that, unlike most Connectors, while inserting an object into an LDAP directory, specify the object class attribute, the $dn attribute as well as other attributes. The following code example, if inserted in the Prolog, defines an objectClass attribute that we can use later.

// This variable used to set the object class attribute 
var objectClass = system.newAttribute ("objectclass"); 
objectClass.addValue ("top"); 
objectClass.addValue ("person"); 
objectClass.addValue ("inetorgperson");
objectClass.addValue ("organizationalPerson");

Then your LDAP Connectors can have an attribute called objectclass with the following assignment:

ret.value = objectClass

To see what kind of attributes the person class has, see http://java.sun.com/products/jndi/tutorial/ldap/schema/object.html

You see that supply an sn and cn attribute in your Update or Add Connector.

In the LDAP Connector, you also need the $dn attribute that corresponds to the distinguished name. When building $dn in the Attribute Map, assuming an attribute in the work object called iuid, you typically have code like the following fragment:

var tuid = work.getString("iuid"); 
ret.value = "uid= " + tuid + ",ou=people,o=example_name.com";

Notes:

The two special attributes, $dn and objectclass usually are not included in Modification in Update mode unless we want to move entries in addition to updating them.
If we cannot connect to our directory, make sure the Use SSL flag in the Configuration is set according to what the directory expects.
When doing a Lookup, we can use $dn as the Connector attribute, to look up using the distinguished name. Do not specify a Simple Link Criteria using both $dn and other attributes; in this case a simple lookup will be done with the DN using an Equals comparison.
Certain servers have a size limit parameter to stop you from selecting all their data. This can be a nuisance as your Iterator only returns the first n entries. Some servers, for example, Netscape/iPlanet, enable you to exceed the size limit if you are authenticated as a manager.
Those servers that return their whole directory in one go (for example, non-paged search) typically cause memory problems on the client side. See Handling memory problems in the LDAP Connector.
When Connector Flags contains the value deleteEmptyStrings, then for each attribute, the LDAP Connector removes empty string values. This possibly leaves the attribute with no values (for example, empty value set). If an attribute has an empty value set then a modify operation deletes the attribute from the entry in the directory. An add operation never includes an empty attribute since this is not permitted. Otherwise, modify entry replaces the attribute values.
When performing a rootdse search in Lookup mode using the "baselevel"search scope, add a Link Criteria specifying that the value of objectClass is * (objectClass equals * ) and leave the Search Base field blank. In Iterator mode the same thing is achieved by leaving the Search Base blank and setting the Search Filter to "objectClass=*".
When performing a normal search in Lookup mode using the "baselevel"search scope, we need to add a valid Link Criteria in accordance with the specified Search Base (for example, Search Base: cn=MyName,o=MyOrganization,c=MyCountry ; Link Criteria: sn equals MySurName).

Detect and handle modrdn operation

Some changelog connectors (the IDS Changelog Connector, Sun Directory Change Detection Connector and zOS Changelog Connector) can detect modrdn operations as the underlying LDAP servers' changelogs provide it. When this happens the Changelog Connector tags the Entry with the modify operation. The changelog attributes contain the "newrdn" attribute when the operation is modrdn. The LDAP Connector detects in its modEntry method if the "newrdn" attribute exists and if so, it replaces the rdn in the target $dn with the new value and does a context rename operation.

LDAP configurations in Delta mode before TDI v7.0 have treated modrdn operation as generic and have not handled it at all. Now they will handle it as modify. Also, such configurations will rename $dn if the "newrdn" attribute is provided.

Configuration

The Connector needs the following parameters; not all parameters are available or visible in all modes:

LDAP URL

The LDAP URL for the connection (ldap://host:port).

Login username

The distinguished name used for authentication to the server.

Login password

The credentials (password).

Search Base

The search base to be used. Specify a distinguished name. Some directories enable you to specify a blank string which defaults to whatever the server is configured to do. Other directory services require this to be a valid distinguished name in the directory. The default value is "<o=orgname>".

Search Filter

The search filter to be used when iterating the directory. This parameter is only used in Iterator mode, but is visible in all modes to help with schema discovery.

The button marked "..." to the right of the Search Filter field presents a Link Criteria dialog where we can fill out a link criteria form and generate the LDAP search filter.

Use the Add button to add more rows to build your selection criteria. The Match Any checkbox will generate an OR expression rather than the default AND expression. Note that this is a one-way helper. Anything you already have in the configuration will be replaced by the generated expression.

Search Scope

This parameter is not used if the Connector is in AddOnly mode. The possible values are:

subtree: Return entries on all levels from search base and below.
onelevel: Only return entries that are immediately below search base.
baselevel: Only return the entry specified by the search base.

The default value is subtree.

Size Limit

A search or iteration must return no more than this number of Entries. 0 = no limit.

Time Limit

Searching for Entries must take no more than this number of seconds. 0 = no limit.

Page Size

If specified, the LDAP Connector tries to use paged mode search. Paged mode causes the directory server to return a specific number of entries (called pages) instead of all entries in one chunk. Not all directory servers support this option. The default value is 0, which indicates that paged mode is disabled.

Sort Attribute

A parameter to specify server side sorting. Does not work with Netscape/iPlanet 4.2.

Increases the strain on the server.

Authentication Method

Type of LDAP authentication. Can be one of the following:

Anonymous - If this authentication method is set then the server, to which a client is connected, does not know or care who the client is. The server allows such clients to access data configured for non-authenticated users. The Connector automatically specifies this authentication method if no username is supplied. However, if this type of authentication is chosen and Login username and Login password are supplied, then the Connector automatically sets the authentication method to Simple.
Simple - using Login username and Login password. Treated as anonymous if Login username and Login password are not provided. Note that the Connector sends the fully qualified distinguished name and the client password in cleartext, unless you configure the Connector to communicate with the LDAP Server using the SSL protocol.
CRAM-MD5 - This is one of the SASL authentication mechanisms. On connection, the LDAP Server sends some data to the LDAP client (that is, this Connector). Then the client sends an encrypted response, with password, using MD5 encryption. After that, the LDAP Server checks the password of the client. CRAM-MD5 is supported only by LDAP v3 servers. It is not supported against any supported versions of Tivoli Directory Server.
SASL - The client (this Connector) will use a Simple Authentication and Security Layer (SASL) authentication method when connecting to the LDAP Server. Operational parameters for this type of authentication will need to be specified using the Extra Provider Parameters option; for example, in order to setup a DIGEST-MD5 authentication we will need to add the following parameter in the Extra Provider Parameters field:
```
java.naming.security.authentication:DIGEST-MD5
```
For more information on SASL authentication and parameters see: http://java.sun.com/products/jndi/tutorial/ldap/security/sasl.html.

Not all directory servers support all SASL mechanisms and in some cases do not have them enabled by default. Check the documentation and configuration options for the directory server you are connecting to for this information.

Use SSL

If this is checked, use Secure Sockets Layer for communication with the LDAP server.

Referrals

Specifies how referrals encountered by the LDAP server are to be processed. The possible values are:

follow - Follow referrals automatically
ignore - Ignore referrals
throw - Throw a ReferralException when a referral is encountered. We need to handle this in an error Hook.

Connector Flags

Flags to enable specific behavior.

deleteEmptyStrings: This flag causes the Connector to remove attributes containing only an empty string as value before updating the directory. If you are using an LDAP version 3 server, use this flag, as the value of an attribute cannot be an empty string.

Extra Provider Parameters

Additional JNDI provider parameters. The format is one colon separated name:value pair on each line.

Return attributes

List of attributes to return (one attribute per line). If you leave this empty, all non-operational (user) attributes are returned. Any operational attributes (such as modifyTimestamp) must still be listed explicitly in order to be returned.

Binary Attributes

A list of attributes that are treated as binary. The format is one attribute name on each line. If this is not specified, a default list of attributes is used. The default list is:

photo
personalSignature
audio
jpegPhoto
javaSerializedData
thumbnailPhoto
thumbnailLogo
userPassword
userCertificate
authorityRevocationList
certificateRevocationList
crossCertificatePair
x500UniqueIdentifier
objectGUID
objectSid

An AssemblyLine can have one list of binary attributes only. If we have several LDAP Connectors in an AssemblyLine, the last Connector must define the list of binary attributes for all the LDAP Connectors in this AssemblyLine if we need to change this from the default.

Auto Map AD Password

Used for adding or updating a user's password in Active Directory using LDAP. When checked, it maps the LDAP password (a conn attribute that must be called userPassword) to another name (unicodePwd). unicodePwd has a special format that the Connector translates into.

Not needed for ADAM.

LDAP Trace File

Trace LDAP BER packets to file; this can be useful for debugging.

Sort Attribute

A parameter to specify server side sorting. Does not work with Netscape/iPlanet 4.2.

This increases the strain on the server.

Virtual List View Page Size

Use Virtual List View for iterations. This might be efficient on some servers, but testing shows that some other servers (for example, Netscape/iPlanet 4.2) are very slow in this respect. However, it does provide a workaround to the out-of-memory problem. Also see Virtual List View Control.

Simulate Rename

If the server does not support rename, simulate it with delete and add operations.

Add Attribute (instead of replace)

This option changes the default behavior of the LDAP Connector when it modifies an entry.

If this checkbox is checked, the LDAP Connector sets the constraint DirContext.ADD_ATTRIBUTE. If this checkbox is not checked, the LDAP Connector sets the constraint DirContext.REPLACE_ATTRIBUTE.

By setting the DirContext.ADD_ATTRIBUTE constraint for the LDAP connection, you add new values to any attribute that goes through the AssemblyLine. This might mean that the same value gets repeatedly added to the entry if not used carefully. This might also result in an exception if the attribute in question is single-valued. If DirContext.REPLACE_ATTRIBUTE is set, the behavior is the same as the old LDAP Connector (default behavior), that is, all values for the attribute are replaced by whatever might be in the work entry.

Comment

Your comments here.

Detailed Log

If this field is checked, additional log messages are generated.

Virtual List View Control

In order to use the Virtual List View Control in TDI 7.1, the JNDI/LDAP Booster Pack from Sun Microsystems needs to be downloaded (http://java.sun.com/products/jndi/downloads/index.html). After downloading the Booster Pack the "ldapbp.jar" contained in the pack needs to be copied to the TDI_install_dir\jars folder before starting TDI. If the Virtual List View control is used, but the "ldapbp.jar" is unavailable, the AssemblyLine will fail with a corresponding error message.

Handling memory problems in the LDAP Connector

Some servers return the whole search result in one go (for example, non paged search) and this typically causes memory problems. It might look to you that IBM TDI leaks memory, but that is just because it is processing the entries from the server while the server continues to pour more and more entries into it.

LDAP servers such as Active Directory support the Paged Search extension that enables you to retrieve a page (the number of objects to return at a time), and this is the preferred way to handle big return sets (see the Page Size parameter for more info on this). We can always test if a server supports the paged search by clicking the button to the right of the Page Size parameter in the LDAP Connector Configuration tab.

If the Page Size parameter is not supported, you might have a problem, since there is little a client can do when being overwhelmed by the Server. Here are some workarounds:

See the Virtual List View Page Size parameter that lets we do a virtual list view. This might or might not be efficient, depending on the LDAP server we use.
If you know that your directory is a size that can be kept in memory, we can increase the memory available to the Java™ VM. See the appendix "Increasing the memory available to the Virtual Machine" in IBM TDI V7.1 Users Guide, and take particular notice of a current issue with the LDAP Connector deployed on AIX.
A general solution to this problem is to use a server-specific utility to dump the LDAP database to an LDIF file or some other file format and then read or iterate that file using a file or URL Connector. A command line can be started in the prolog (before Connectors activated using system.shellCommand), producing the LDIF export and then the AssemblyLine reads that file. It is an effective solution, when possible to implement. Remember that if you are in a mode where you iterate whole, large directories, you are able to do implement as a batch.
In some cases we can even use IBM TDI to dump the directory search to file. This is possible because writing quickly to a file might enable IBM TDI to access enough of the data to keep up with the feed (depending on the amount of data and the speed of the feed). If your AssemblyLine takes too long to process an entry (for example, if it is updating another directory), the entry flood happens sooner. However, this solution is very time dependent and must be avoided if we have a better method.

Built-in rules for reconnect functionality

The Connector has implemented logic for reconnect processing as of TDI v6.1.1 fixpack 2. The Connector-specific built-in rules makes it possible to perform a reconnect if javax.naming.ServiceUnavailableException is thrown regardless of the message.

In versions of TDI before v7.1, the Connector had a loop that tried 10 times to establish the initial connection. This was to work around a problem with some servers, but it had the side effect that a failure to establish the initial connection could take a very long time if the server was down. In v7.1, this "loop" is moved into reconnect rules instead. This way you may specify if a reconnect attempt should take place, and also how many times it should be tried. For backwards compatibility, initial reconnection is enabled.

Searching against an SDBM backend on z/OS

When using the LDAP Connector for searches against an SDBM backend on z/OS, we need to consider the following:

When an LDAP Connector in Iterator mode is used to get a list of user profiles on an z/OS SDBM (LDAP) service, by default only the DN Attribute is returned. Other attributes are not returned even with a "*" attribute specified in the input map. This is a known limitation of the LDAP connector (it was not originally intended for this). To retrieve all the attributes, construct the AssemblyLine such that we use the LDAP Connector first in Iterator mode to retrieve the DN and subsequently use the LDAP Connector in Lookup mode with Link Criteria using the DN (that is, Link Criteria set to "$dn EQUAL $$dn").

Here a "presence" filter is used in the Iterator Connector's configuration (Config Tab-> Search Filter) to determine the scope of DN to retrieve and an subsequent equivalence filter is used in the Link Criteria in an LDAP connector in Lookup mode.
There are 3 user profiles for which the Iterator/Lookup flow does not work with an SDBM backend on z/OS:
- $dn 'racfid=irrmulti,profiletype=user,sysplex=sysb'
- $dn 'racfid=irrsitec,profiletype=user,sysplex=sysb'
- $dn 'racfid=irrcerta,profiletype=user,sysplex=sysb'
The lookup may get the following error on these user profiles: 'ICH30001I UNABLE TO LOCATE USER' or 'ICH31005I NO ENTRIES MEET SEARCH CRITERIA'. This happens because these users are not real users and therefore should not be the subject of searches. The SDBM backend will do a "listuser" under the covers that issues the request in uppercase and therefore, will not find the profiles. This is expected behavior.

LDAP Connector methods (API)

This section describes some of the methods available in the LDAP Connector. The exhaustive API reference is in the JavaDocs; they can be viewed by choosing Help -> Welcome screen, JavaDocs link in the Config Editor.

LDAP compare

public boolean compare(String compdn, String attname, String attvalue) 
    throws Exception

where

compdn is the DN on which we want to compare an attribute.
attname is the name of the attribute you want to compare.
attvalue is the value for attvalue that we want to check comparison for.

If the value is equal, true is returned. If the value is not equal, the value false is returned. For example, if we wanted to determine if the userpassword attribute for cn=joe,o=ibm was equal to secret, use the method: compare("cn=joe,o=ibm", "userpassword", "secret").

Adding a value to an attribute

This method adds a given value to an attribute:

public void addAttributeValue(String moddn, String modattr, String modval) 
    throws Exception

where

moddn is the DN to which we want to add the attribute value.
modattr is the name of the attribute you want to add a value to.
modval is the value we want to add to modattr.

For example, if we want to add cn=bob to the members attribute of cn=mygroup, use the method: addAttributeValue("cn=mygroup", "members", "cn=bob")

A java.langException is thrown when the underlying modify operation fails.

Replacing an attribute value

This method replaces a given value for an attribute:

public void replaceAttributeValue(String moddn, String modattr, String modval) 
    throws Exception

where

moddn is the DN for which we want to replace the attribute value.
modattr is the name of the attribute you want to replace a value for.
modval is the value we want to replace for modattr.

For example, if we want to replace the members attribute of cn=mygroup with only cn=bob, use the method: replaceAttributeValue("cn=mygroup", "members", "cn=bob")

A java.langException is thrown when the underlying modify operation fails.

Removing an attribute value

This method removes a given value from an attribute:

public void removeAttributeValue(String moddn, String modattr, String modval) 
    throws Exception

where

moddn is the DN for which we want to remove the attribute value.
modattr is the name of the attribute from which we want to remove a value.
modval is the value we want to remove from modattr.

For example, if we want to remove the value cn=bob from the attribute members in the DN cn=mygroup, use the method: removeAttributeValue("cn=mygroup", "members", "cn=bob")

A java.langException is thrown when the underlying modify operation fails.

Removing all attribute values

This method removes all values for a given attribute:

public void removeAllAttributeValues(String moddn, String modattr) 
    throws Exception

where

moddn is the DN from which we want to remove the attribute values.
modattr is the name of the attribute from which we want to remove all values.

For example, if we want to remove all values of the members attribute of cn=mygroup, use the method: removeAllAttributeValues("cn=mygroup", "members")

A java.langException is thrown when the underlying modify operation fails.

Flag in Config Editor for default action for attribute add or replace

In the LDAP Connector Config Editor there is a checkbox named Add Attributes (instead of replace). This option changes the default behavior of the LDAP Connector when it modifies an entry.

If this checkbox is checked, the LDAP Connector sets the constraint DirContext.ADD_ATTRIBUTE. If this checkbox is not checked, the LDAP Connector sets the constraint DirContext.REPLACE_ATTRIBUTE.

By setting DirContext.ADD_ATTRIBUTE constraint for the LDAP connection, you add new values to any attribute that goes through the AssemblyLine. This might mean that the same value gets repeatedly added to the entry if not used carefully. This might also result in an exception if the attribute in question is single-valued. If DirContext.REPLACE_ATTRIBUTE is set, the behavior is the same as the old LDAP Connector (default behavior), that is, all values for the attribute are replaced by whatever might be in the work entry.

You typically want this flag set when you are handling groups. If we want to add a member (a value) to a group (an attribute), we do not want to delete all the other values.

The old behavior was to replace the attribute with the new value. This behavior remains the default.

This property can be set at any time while the Connector is running by setting the property addAttribute from the scripts. Use something similar to the following command:

work.setProperty("addAttribute", true)

This property does not affect the behavior of the addAttributeValue and replaceAttributeValue methods described previously.

Rebind

The LDAP Connector has a rebind() method which facilitates building advanced solutions like virtual directories and other solutions that map incoming authentication requests (use any of the support protocols) to LDAP. See the JavaDocs for more information.

Skip Lookup in Update and Delete mode

The LDAP Connector supports the Skip Lookup general option in Update or Delete mode. When it is selected, no search is performed prior to actual update and delete operations. It requires a $dn parameter to be specified in order to operate properly.