The Shibboleth V1 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.
JNDIDataConnector
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