Configuring a LDAP Data Connector

The LDAP connector allows you to pull attributes from data stores that can be access through a Java JNDI interface (which is most LDAP, version 3, compliant servers). This connector pools connections in order to enhance performance. See the advanced configuration section in order to disable this.

Configuring the Connector

1. Create a JNDIDirectoryDataConnector with its id attribute and optional attributes:
   • useStartTls - true if startTLS should be used, defaults to false
   • mergeMultipleResults - true if a query that returns multiple results should have the attributes (and values) from each result merged into a single result, defaults to false
   • noResultIsError - _ true_ if an LDAP query that does not return a result is an error, defaults to true
2. Create a Search element, as a child of JNDIDirectoryDataConnector, with an attribute, filter, whose value it the LDAP search filter to use. The macro %PRINCIPAL% may be used to insert the current principal's name into the search filter.
3. Optionally, a Controls element with any of the following attributes:

   Attribute Name	Attribute Value	Usage
   searchScope	OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE	Scope of the search; particular objeclasses, LDAP URL specified level only, or LDAP URL and its descendants, respectively
   returningAttributes	comma seperated list of attribute names	The attributes to be returned from a search. Limiting the number of attribute to only those you need can greatly increase performance
   timeLimit	0 - 2^31^-1	number of milliseconds to wait for a search to return, 0 indicates wait forever
   countLimit	0 - 2^63^-1	maximum number of results to return in a query
   returningObjects	true or false	whether to return only objectclass definitions
   linkDereferencing	true or false	whether to dereference LDAP links, not the same thing as LDAP referrals

4. Optionally, create Property elements, children of the JNIDDirectoryDataConnector element, with attributes name and value containing the following values as appropriate

   Name Attribute	Value Attribute	Usage
   java.naming.factory.initial	com.sun.jndi.ldap.LdapCtxFactory	The factory used to produce LDAP connections
   java.naming.provider.url	ldap://ldap.example.edu/dc=example,dc=edu (example)	The URL of the LDAP server to connect too
   java.naming.referral	ignore, follow, throw	Whether to ignore, follow, or throw an exception when an LDAP referral is received
   java.naming.security.principal	cn=admin,dc=example,dc=edu (example) I The DN of the user to bind to the directory
   java.naming.security.credentials	examplepw	The password for the user binding to the directory
   java.naming.security.protocol	ssl	To connect to the LDAP over SSL
   com.sun.jndi.ldap.connect.pool	true or false	Whether to pool connections or not. This option is specific to the Sun LDAP connection factory.
   com.sun.jndi.ldap.connect.pool.initsize		Number of connections to create when the pool is created. This option is specific to the Sun LDAP connection factory.
   com.sun.jndi.ldap.connect.pool.prefsize		Number of connections that should be kept around in the pool. This option is specific to the Sun LDAP connection factory.
   com.sun.jndi.ldap.connect.pool.authentication	none simple	The methods used to authentication users. This option is specific to the Sun LDAP connection factory.
   com.sun.jndi.ldap.connect.pool.protocol	plain ssl	The protocols available to communicate to the server. This option is specific to the Sun LDAP connection factory.

A more exhaustive list of these properties can be found on the Sun JNDI site.

Example Configuration

This example demonstrates a basic configuration without pooling or SSL

<JNDIDirectoryDataConnector id="directory">
	 <Search filter="cn=%PRINCIPAL%">
		  <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
	 </Search>
	 <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
	 <Property name="java.naming.provider.url" value="ldap://ldap.example.edu/dc=example,dc=edu" />
	 <Property name="java.naming.security.principal" value="cn=admin,dc=example,dc=edu" />
	 <Property name="java.naming.security.credentials" value="examplepw" />
</JNDIDirectoryDataConnector>

This example demonstrates a configuration that uses LDAP over SSL to communicate with the directory. This assumes that the LDAP certificate has been imported the JVMs trust store.

<JNDIDirectoryDataConnector id="directorySecure">
	 <Search filter="cn=%PRINCIPAL%">
		  <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
	 </Search>
	 <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
	 <Property name="java.naming.provider.url" value="ldap://ldap.example.edu:636/dc=example,dc=edu" />
	 <Property name="java.naming.security.protocol" value="ssl" />
	 <Property name="java.naming.security.principal" value="cn=admin,dc=example,dc=edu" />
	 <Property name="java.naming.security.credentials" value="examplepw" />
</JNDIDirectoryDataConnector>

This example demonstrats a configuration that pools LDAP connections.

<JNDIDirectoryDataConnector id="directoryPooled">
	 <Search filter="cn=%PRINCIPAL%">
		  <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
	 </Search>
	 <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
	 <Property name="java.naming.provider.url" value="ldap://ldap.example.edu/dc=example,dc=edu" />
	 <Property name="com.sun.jndi.ldap.connect.pool" value="true" />
	 <Property name="com.sun.jndi.ldap.connect.pool.initsize" value="5" />
	 <Property name="com.sun.jndi.ldap.connect.pool.prefsize" value="5" />
	 <Property name="com.sun.jndi.ldap.connect.pool.authentication" value="none simple DIGEST-MD5" />
	 <Property name="com.sun.jndi.ldap.connect.pool.protocol" value="plain ssl" />
</JNDIDirectoryDataConnector>