Metamerge logo
Search

Advanced Search
*
*
*
* HOME DOCUMENTS & RESOURCES DOWNLOADS EARLY TECH ACCESS SUPPORT FAQ KNOWN ISSUES OLD VERSIONS
*

LDAP Connector version 1.27

Overview

The LDAP Connector provides access to a variety of LDAP based systems. The Connector supports both LDAP version 2 and 3.  

Note that, unlike most Connectors, while inserting an object into an LDAP directory, you have to specify the object class attribute, the $dn attribute (distinguished name) as well as the other attributes. The following code sample, if inserted in the Prolog, will define an objectClass attribute that you will be able to 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://ldap.hklc.com/objectclass.html?objectclass=person . You will there see that you must supply a sn and cn attribute in your update/add Connector)

In the Connector, you will 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 will typically have code like

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

Note that the two special attributes $dn and objectclass should usually not be included in Modification in Update mode unless you want to move entries in addition to updating them.

Configuration

The Connector needs the following parameters:

Parameter

Description

connectorType com.architech.connector.rscLdap
ldapUrl The LDAP URL for the connection. (ldap://host:port)
ldapUsername The distinguished name used for authentication to the server
ldapPassword The credentials (password)
ldapSearchBase The search base to be used when iterating the directory. Specify a distinguished name. Some directories allow 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.
ldapSearchFilter The search filter to be used when iterating the directory.
ldapSearchScope The possible values are
  • subtree - Return entries on all levels from search base and below
  • onelevel - Only return entries that are immediately below searchbase
ldapTimeLimit Searching for Entries should take no more than this number of seconds. 0 = no limit. 
ldapSizeLimit A search (or iteration) should return no more than this number of Entries. 0 = no limit.
ldapAuthenticationMethod Type of LDAP authentication.  Can be one of the following:
  • Simple (using ldapUsername/ldapPassword). Treated as anonymous if username/password not provided)
  • MD5-CRAM
  • SASL
  • Anonymous (treated as Simple if username and password are supplied)

 

ldapPageSize A number.
If specified the LDAP Connector will try to use paged mode search. Paged mode cause 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.
ldapUseSSL If this is checked, use secure sockets layer for communication with the LDAP server. Refer to Certificate Manager in order to register your certificates.
ldapReferrals 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. You need to handle this in an error Hook.

connectorFlags 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. See Notes for a full explanation. If you are using a LDAP version 3 server, you should definitely use this flag as the value of an attribute cannot be an empty string.

jndiExtraProviderParams Additional JNDI provider parameters. The format is one colon separated name:value pair on each line.
ldapReturnAttributes List of attributes to return (one attribute per line). If you leave this empty, all attributes will be returned.
ldapBinaryAttributes 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. As of version 4.6.3, the default list is "photo personalSignature audio jpegPhoto javaSerializedData thumbnailPhoto thumbnailLogo userPassword userCertificate authorityRevocationList certificateRevocationList crossCertificatePair x500UniqueIdentifier objectGUID objectSid";

Note: An AssemblyLine can only have one list of binary attributes. If you have several LDAP connectors in an AssemblyLine, the last connector should define the list of binary attributes for all the LDAP connectors in this AssemblyLine (if you need to change this from the default).

automapADPassword Used for adding/updating a user's password in AD using LDAP. When checked, will  map LDAP password (a con attribute that must be called userPassword) to another name (unicodePwd).  unicodePwd has a special  format that the Connector will translate into.

This will not work with the JSSE libraries delivered with Integrator version 4.6: You need at least version 1.0.2 of the JSSE libraries for automapADPassword to work (see http://java.sun.com/products/jsse/INSTALL.html ).  The old JSSE version only supports 40bit RC4, while AD uses 128bits.

ldapBERTrace Trace LDAP BER packets to file
ldapSortAttribute A new parameter to specify server side sorting . Does not work with Netscape 4.2! Note that this will increase the strain on the server
ldapVLVPageSize Use  Virtual List View for iterations. This may be efficient on some servers but  testing shows that Netscape 4.2 is really slow in this respect. However, it does work around the out of memory problem.

Notes

  • If you cannot connect to your directory, make sure the  Use SSL flag (under Configuration) is set according to what the directory expects ...
  • When doing a Lookup, you 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.
  • When connectorFlags contains the value {deleteEmptyStrings} then for each attribute, the LDAP Connector will remove empty string values. This will possibly leave the attribute with no values (i.e. empty value set) If an attribute has an empty value set then a modify operation will DELETE the attribute from the entry in the directory. An add operation will never include an empty attribute since this is not "legal". Else modify entry will REPLACE the attribute value(s) 
  • Certain servers have a size limit parameter to hinder you from selecting (and stealing?) all their data (or crash your client).  This can be a nuisance as you iterator will only return the first n entries. 
    Some servers will allow you to exceed the size limit if you are authenticated as a manager (Netscape/iPlanet). 

  • Those servers that return their whole directory in one show (e.g. non paged search) will typically cause memory problems on the client side. Check the section about Handling Memory Problems for more on this.

  • When connectorFlags does NOT contain {deleteEmptyStrings} then empty strings are passed as legal values to the directory server. Most servers interpret a REPLACE request with an empty string as the same as removing the attribute altogether. If you want to control this behavior yourself you can always call a function in your "Before Update" handler to modify the entry as in: 
removeBlanks (work);
function removeBlanks (entry) {
	var list = entry.getAttributeNames();
	for (i = 0; i < list.length; i++) {
		if (entry.getString(list[i]) == "") {
			entry.removeAttribute (list[i]);
		}
	}
}
  •  

Handling memory problems in the LDAP Connector

Some servers return the whole search result in one show (e.g. non paged search) and this will typically cause memory problems. It might look to you that Integrator 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 like AD support the "Paged Search" extension that allows you to retrieve a "page" (some client/server agreement on number of objects to return at a time), and this is of course the preferred way to handle big return sets (see the ldapPageSize  parameter for more info on this). You can always test if a server supports the paged search by clicking the button right of the "Page Size" parameter in the LDAP Connector.  

If the Page Size parameter is not supported, you might have some real problem, since there is little a client can do when being bombed by the Server.  Here are a couples of work around: 

Check out the ldapVLVPageSize parameter that lets you do a virtual list view.  This might or might not be efficient, depending on the LDAP server you use.

If you know that your directory is of a size that can be kept in memory, you can increase the memory available to the Java VM as described in the FAQ.  This of course, will only work if your directory searches return a limited amount of data.

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 (iterate) that file using a file/url Connector. A command line could be executed in the prolog (before connectors activated using system.shellCommand), producing the LDIF export and then the AL would read that file. It turns out to be an effective solution when possible.  Remember that if you are in a mode where you iterate whole (and big) directories, you probably are able to do it as batch (as this will be).

In some cases you could even use Integrator to dump the directory search to file:  This is actually possible since writing quickly to a file might (depending on the amount of data and the speed of the feed) let Integrator swallow enough of the data to keep up with the feed.  If your AssemblyLine takes to long time to process an entry (such as it will if it is updating another directory), the entry flood will happen earlier.  However, this solution is very timing dependent and should be avoided if you have a better method.

See Also

JNDI Connector

*
  Metamerge Integrator version 4.6 ©Copyright Metamerge AS 2000-2002 Last edited 2002-06-10 contact us