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.

Data Connector Basics

All data connectors are configured in the IdP's resolver.xml configuration file.

Each connector is defined with an XML element that requires an id attribute. This attribute is used to reference the connector from other connectors and attribute definitions. To make future maintenance easier we encourage you to use an meaningful name for id attribute.

Configuring the Connector

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

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

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.

Active Directory users

Active Directory has a number of deployment configurations that may prevent LDAP referrals from working properly. If you are using LDAP directories it is strongly suggested that you set the java.naming.referral property to ignore.

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>

Data Connector Dependencies

In order to use attributes from other connectors or attribute definitions you need to make sure those dependencies are resolved before this connector is called.

If your connector depends on another connector create a child element, of main connector element, called DataConnectorDependency and give it an attribute of requires whose value is the id of the connector this connector depends on.

If your connector depends on an attribute definition create a child element, of the main connector element, called AttributeDependency and give it an attribute of requires whose value is the id of the definition this connector depends on.

Failover Dependency

A connector can specify a special type of dependency, called a failover dependency. If the data connector is unable to fetch any attributes the connector specified in the failover dependency will be invoked.

To specifiy a failover dependency create a child element, of main connector element, called FailoverDependency and give it an attribute of requires whose value is the id of the connector this connector depends on.

Error Propagation

Not every data connector may, or need, work for every user in the system. However, the connector may emmit an error if it is unable to find any entries for the user or if it depends on another connector or attribute definition that didn't apply to the current user.

To suppress these errors, so that they don't stop the attribute lookup process, add the follow attribute and value to the main connector element:

propagateErrors - with a value of false

Data Caching

Data connectors cache its information for the length of one attribute request; until all connectors and attribute definitions have been evaluated and their information retrieved. You may optionally have the connectors cache their data for a fixed period of time. This can increase performance but will result in a lead time for frequently changing data.

To enable this longer-lived cache add the following attribute to the main connector element:

cacheTime - the length of time, in seconds, to cache the attributes fetched by this connector