Configuring LDAP as a back-end relies on beans defined via an import in authn/password-authn-config.xml:
Import in authn/password-authn-config.xml
<import resource="ldap-authn-config.xml" />The properties in ldap.properties do most of the work out of the box. Adding additional beans may be needed in very advanced cases where a higher degree of control is required.
These beans also act as global defaults that can be overridden on specific instances of beans inheriting from shibboleth.LDAPValidator defined in authn/password-authn-config.xml in the shibboleth.authn.Password.Validators bean.
In the simple case of LDAP used alone:
Defining use of LDAP in password-authn-config.xml
<util:list id="shibboleth.authn.Password.Validators">
<!-- Default bean uses the settings defined in ldap-authn-config.xml and ldap.properties -->
<ref bean="shibboleth.LDAPValidator" />
</util:list>If desired, it's possible to directly configure the various settings within the validator bean instead of or in addition to relying on the defaults.
As an example, you could chain together multiple LDAP servers (rather than hoping the client library will do it for you) like this:
Chaining LDAP validators
<!--
These use the settings defined in ldap-authn-config.xml and
ldap.properties except the ones overridden here.
You can override any parameter (like p:ldapUrl) that can be defined for a
shibboleth.LDAPAuthenticationFactory, see system/flows/authn/password-authn-beans.xml
-->
<util:list id="shibboleth.authn.Password.Validators">
<bean p:id="ldap1" parent="shibboleth.LDAPValidator">
<property name="authenticator">
<bean parent="shibboleth.LDAPAuthenticationFactory" p:ldapUrl="ldaps://ldap1.example.org" />
</property>
</bean>
<bean p:id="ldap2" parent="shibboleth.LDAPValidator">
<property name="authenticator">
<bean parent="shibboleth.LDAPAuthenticationFactory" p:ldapUrl="ldaps://ldap2.example.org" />
</property>
</bean>
</util:list>Note Regarding Upgrades
The ldap-authn-config.xml file has changed dramatically since V3 and is now very short, relying primarily on a special bean with a hidden parent definition taking a large set of properties that will generally auto-configure the proper objects.
Updating the the newer ldap-authn-config.xml
While the older, longer file should work in most cases, it is a good idea to look at updating to the new file from the distribution.
Having said that, copying the new file in will break initially unless you also explicitly define the bean called shibboleth.authn.Password.Validators (shown above), which is present by default in password-authn-config.xml in new installs. For LDAP alone, the example above generally suffices.
One issue that does come up with the older file: the defaults around pooling validation in V3 were expressed numerically in seconds, and these numbers are interpreted in V4 as milliseconds. The proper syntax is really XML Duration syntax (PT5M == 5 minutes) and not numerically, but out of the box using the old file with V4 and not setting some of the pooling properties will result in dramatically frequent pool validation on the order of every half second. The logs will be very noisy so it's quite obvious.
To correct this, either update to the V4 file (and define the new bean noted above), or change the property defaults in the old file, or actually set the properties themselves rather than leaving them commented.