LDAPAuthnConfiguration
Current File(s): conf/authn/password-authn-config.xml, conf/ldap.properties, conf/authn/authn.properties
Format: Native Spring, Properties
Overview
The LDAPCredentialValidator for the password authentication login flow uses native LDAP libraries for password-based authentication instead of using a JAAS module. The primary advantages are slightly better performance and more control over the process, such as the ability to extract detailed account status information from the directory during a login. One disadvantage is that JAAS configurations may be reloaded each time they're used, while the native configuration is static.
General Configuration
Configuring LDAP as a back-end relies on beans internally that are configured using ldap.properties (defined separately from other properties because they are sometimes shared for LDAPConnector configuration).
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, and can be placed within authn/password-authn-config.xml.
The properties 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.properties -->
<ref bean="shibboleth.LDAPValidator" />
</util:list>It's possible to directly configure the various settings within the validator bean instead of or in addition to relying on the defaults. Typically this involves injecting a bean based on shibboleth.LDAPAuthenticationFactory into the validator bean’s authenticator property. This is a large factory class of type net.shibboleth.idp.authn.config.LDAPAuthenticationFactoryBean that includes most common LDAP settings.
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.properties except the ones overridden here.
-->
<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>The following sections describe how to configure a single instance of an LDAP CredentialValidator.
Authenticator Configuration
The idp.authn.LDAP.authenticator property controls the workflow for how authentication occurs against the LDAP directory for most “simple” cases by automatically configuring a number of underlying objects based on a set of built-in “authenticator types” supported by the ldaptive library.
anonSearchAuthenticator | Performs an anonymous search for the user's DN |
bindSearchAuthenticator | Binds with a configured DN as a service account, then searches for the user's DN |
directAuthenticator | User DNs are of a known format. i.e. CN=user_name,ou=accounts,dc=domain,dc=edu. No DN search is performed. |
adAuthenticator | Configuration that leverages the AD specific @domain.com format. No DN search is performed since AD supports binding directly with that user name. |
Depending on the choice above, various other properties must be set (see the reference section below).
Connection Configuration
Use the following properties to configure basic connection information for the LDAP directory:
idp.authn.LDAP.ldapURL
idp.authn.LDAP.useStartTLS
idp.authn.LDAP.connectTimeout
A connection pool is used, and there are several properties used to configure pool behavior (see the reference below).
SSL Configuration
If StartTLS or SSL are used, a source of trust anchors must be configured to control certificate validation, using the idp.authn.LDAP.sslConfig property:
certificateTrust | Uses the idp.authn.LDAP.trustCertificates property to load a resource containing the trust anchors (such as a file of PEM-format certificates) |
keyStoreTrust | Uses the idp.authn.LDAP.trustStore property to load a keystore containing the trust anchors |
jvmTrust | Uses the default JVM trust anchors (the JVM-wide "cacerts" file) |
disabled | Does not allow SSL or startTLS connections. |
We have tentative plans to deprecate the “jvmTrust” option, which has already been removed from the attribute resolution side of the software, as it is bad practice and has been a source of serious security flaws.
Reference
Advanced Features
Note that for some advanced use cases, it may be necessary to dig deeply into the Ldaptive documentation and wire up custom objects using, or based on beans in the older V3 version of authn/ldap-authn-config.xml, ultimately installing an instance of org.ldaptive.auth.Authenticator into the "authenticator" property of a particular LDAPCredentialValidator bean. Most of the flexibility comes from all the various types of objects that can be injected into instances of the Authenticator class.