LDAP Connector
Note: A newer version of this Connector exists.
This documentation covers the LDAP connector you
will get when you download Integrator 4.6. See
..\..\Downloads\ETA\ldap.htm .
The new version has improved functionality as well fixed bugs.
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 |
This parameter is only used if the Connector is
in Iterator mode. 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.
|
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.
|
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).
|
- 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]);
}
}
}
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:
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.
Usually, the best way to do this is to export (using LDIF) from one server,
and then importing it to the other. If you for some reason want to do this
on-the fly, read the following discussion.
See Also
JNDI Connector
|