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