The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
The LDAPDirectory data connector generates one or more attributes based on a query to an LDAP directory.
The underlying library used for this is called ldaptive, and many of the more advanced options are usable only by referring to its documentation, but most deployers should be able to make to do with the information we supply.
General Configuration
The IdP ships with an example configuration file (conf/examples/attribute-resolver-ldap.xml), that demonstrates property-driven attribute resolution, using the properties defined in ldap.properties, much of which can be shared with the LDAP Authentication Configuration for the common case of a single LDAP directory used for both authentication and attributes. You can freely mix use of properties with explicit settings.
If execution of the query returns multiple results, these are merged by default.
The following properties are demonstrated. They take their defaults from the values of the similarly-named authentication properties, but can be explicitly set to split them off as needed.
Property
Type
Default Authn Property
Function
Property
Type
Default Authn Property
Function
idp.attribute.resolver.LDAP.ldapURL
URL
idp.authn.LDAP.ldapURL
Connection URL for the LDAP directory
idp.attribute.resolver.LDAP.baseDN
String
idp.authn.LDAP.baseDN
Base DN to search against,
idp.attribute.resolver.LDAP.bindDN
String
idp.authn.LDAP.bindDN
DN to bind as before performing the search
idp.attribute.resolver.LDAP.bindDNCredential
String
idp.authn.LDAP.bindDNCredential
Password to bind with before performing the search
idp.attribute.resolver.LDAP.useStartTLS
Boolean
idp.authn.LDAP.useStartTLS (defaults true)
Whether StartTLS should be used immediately after connecting to the LDAP
idp.attribute.resolver.LDAP.trustCertificates
Resource
idp.authn.LDAP.trustCertificates
A resource to load trust anchors from, usually a local file in %{idp.home}/credentials
idp.attribute.resolver.LDAP.connectTimeout
Duration
idp.authn.LDAP.connectTimeout (defaults PT3S)
Connection timeout in milliseconds
idp.attribute.resolver.LDAP.responseTimeout
Duration
idp.authn.LDAP.responseTimeout (defaults PT3S)
Time to wait for response
idp.attribute.resolver.LDAP.connectionStrategy
Enumeration
ACTIVE_PASSIVE
Connection strategy to use when multiple URLs are supplied, one of ACTIVE_PASSIVE, ROUND_ROBIN, RANDOM
TLS Validation Configuration
Assuming either LDAP-over-TLS (ldaps) or StartTLS are used, you MUST configure the rules for validating the LDAP server's TLS key within the connector.
There are generally two ways to do this:
Reference a CA (Certificate Authority) that has signed the certificate chain presented by the LDAP server.
Reference the LDAP server's certificate explicitly.
The latter provides better security but likely will require constant updating and coordination with the LDAP server's operational staff unless it relies on a longer-lived certificate.
You may configure multiple certificates by concatenating PEM formatted certificates together.
You reference the certificate(s) you choose to trust by setting the trustFile XML attribute inside the <DataConnector> element, and the example below passes that through to a property you can configure separately, but that's purely a matter of style.
Note that this is distinct from configuring the IdP to authenticate itself to the LDAP server with a certificate. That relies on a different set of options (authKey, authCert).
URL(s) to the LDAP server. Each listed URL is tried according to the connectionStrategy.
baseDN
String
Base DN from which the LDAP search will be executed
principal
String
Username (service DN) that the connector will use to bind to the LDAP directory
principalCredential
String
Password used to authenticate as the principal (service DN)
lowercaseAttributeNames
Boolean
false
Whether all attribute IDs from the LDAP should be lower-cased. This can be important since Shibboleth attribute IDs are case-sensitive while LDAP attribute IDs are not.
trustFile
File pathname
Path to a file containing the X.509 trust information to use when connecting to the directory over LDAPS or startTLS. Replaces the deprecated use of <StartTLSTrustCredential>
failFastInitialize
Boolean
true
Whether a failure when verifying the LDAP server's availability during startup is fatal (stops the Attribute Resolver service from starting)
connectTimeout
Duration
PT3S
Time to wait for a connection to be established
responseTimeout
Duration
PT3S
Time to wait for a response before failing
searchTimeLimit
Duration
PT3S
Length of time that a search operation should execute; a value of 0 means execute indefinitely; when time limit arrives the result will contain any entires returned up to that point
maxResultSize
Integer
1
Maximum number of entries to allow in the search result; a value of 0 means includes all entries. Exceeding this value will result in a failure of the connector.
noResultIsError
Boolean
false
Whether an empty result set is an error
multipleResultsIsError
Boolean
false
Whether a result set with more than one result is an error
connectionStrategy
One of ROUND_ROBIN, RANDOM, ACTIVE_PASSIVE
ACTIVE_PASSIVE
If Multiple URLs were provided as the ldapURL this describes how each URL will be processed.
ACTIVE_PASSIVE (default value) - Indicates that the first LDAP URL will be used for every request unless it fails and then the next LDAP URL will be used.
ROUND_ROBIN - Indicates that for each new connection the next LDAP url in the list (circling back to the start of the list when the end is reached) will be used
RANDOM - Indicates that for each new connection a random LDAP url will be selected
searchScope
One of SUBTREE, ONELEVEL, OBJECT
SUBTREE
The scope of the search.
SUBTREE: The entire LDAP directory subtree below the search baseDN will be searched.
ONELEVEL: Only the immediate children of LDAP object corresponding to the search baseDN will be searched.
OBJECT: Only the LDAP object itself is searched.
derefAliases
One of NEVER, SEARCHING, FINDING, ALWAYS
NEVER
How aliases should be dereferenced. See the Oracle JNDI docs for more details on these options.
followReferrals 4.0.1
Boolean
false
Whether to follow search referrals and references when they are encountered in search results.
useStartTLS
Boolean
false
Whether to use startTLS when connecting to the LDAP
disableHostnameVerification
Boolean
false
Whether to enforce certificate name checking during TLS, only change if you understand the implications
authCert
File pathname
Path to the file containing the X.509 certificate to provide when connecting to the directory over LDAPS or startTLS
authKey
File pathname
Path to the file containing the private key to provide when connecting to the directory over LDAPS or startTLS
A list of attributes to be returned from the LDAP directory server; this may help the server respond more quickly
<BinaryAttributes>
0 or 1
A list of attributes whose values contain binary data and must be base64 encoded; format is a space-delimited list of attribute names, which MUST match the directory source exactly (including case and any LDAP options)
X.509 client authentication information to provide when connecting to the directory over LDAPS or startTLS, DEPRECATED in favor of the authCert, authKey, and authKeyPassword attributes
The definition of how results should be cached as an externally defined Cache<String,Map<String,IdPAttribute>>, the Spring bean ID of which is supplied as the content of the element
Spring Configuration
The springResource and springResourceRef attributes DEPRECATED in V4.3 and will not work in V5
If the springResource or springResourceRef attributes are specified, then the configuration of the DataConnector bean is delegated to the supplied resources. The system will create a factory for an LDAPDataConnector object, and look for beans in the Spring resource(s) supplied that match the types of properties supported by that type and its parent classes.
In V4+, many of these classes and interfaces have been moved into the public API.
In practice, the data connector may be supplied with Spring-defined beans of the following types: