Skip to end of metadata
Go to start of metadata
Table of Contents

LDAP Authentication Handler

Including the Handler

In the pom.xml file for your CAS Maven2 WAR Overlay, add the following dependency:

Icon

Version 3.3.5, due to a mistake in its build, included this by default. Prior and future versions do not include it by default.

You'll also need to create a new property in the pom file with the name "apache.commons.pool.version" and give the value of the apache commons pool version you intend to use, (i.e 1.5.6) if connection pooling is needed.

Core Classes

You need to decide how you would like CAS to authenticate the credentials. Should it merely attempt to authenticate to (bind to) the LDAP server using the credentials directly as the user? Or should it first look up the user in some subtree and then attempt to bind as that user? It is more efficient and more secure to use fastbind, but that is not always possible. This is explained in detail later in this document.

Both methods require you to configure an LDAP context bean: this is the configuration to access your directory. It is recommended to configure a new bean in the top list and reference that from the configuration of the AuthenticationHandler, as explained in the instructions on this page.

FastBindLdapAuthenticationHandler

Use this handler when a user DN may be directly composed from the username, e.g. uid=%u,ou=people,dc=vt,edu, where %u is the username provided on the CAS login form.

The FastBindLdapAuthenticationHandler supports the following properties:

  • filter - The filter property is the LDAP filter that will be used for the search. When constructing the filter, wherever you want the username to appear, place a "%u".
  • ignorePartialResultException - This property informs Spring LDAP to ignore PartialResultExceptions that may get thrown when connecting to an Active Directory.
  • contextSource - This is a reference to a LdapContextSource (see below) which will contain the settings for connecting to the LDAP server.

BindLdapAuthenticationHandler

This component performs a typical two-phase LDAP authentication process:

  1. Search for the user DN based on an arbitrary search filter.
  2. Construct the DN and bind with it using the password from the CAS login form.

Use this handler when the DN cannot be directly composed from the username, for example when the directory uid is an opaque identifier that is distinct from a memorable username or the common sense of username is based on an alternative attribute such as mail (email address). Since two LDAP operations are performed for every authentication, this method is inherently less efficient than FastBindLdapAuthenticationHandler and should be used when required.

The BindLdapAuthenticationHandler supports the following properties:

  • filter - The filter property is the LDAP filter that will be used for the search. When constructing the filter, wherever you want the username to appear, place a "%u".
  • ignorePartialResultException - This property informs LdapTemplate to ignore PartialResultExceptions that may get thrown when connecting to an Active Directory.
  • contextSource - LdapContextSource used for the LDAP bind operation. (And search in versions prior to 3.4.9).
  • searchContextSource - New in 3.4.9 LdapContextSource used for the LDAP search operation. This property is intended to support LDAP connection pooling for improved performance. See https://issues.jasig.org/browse/CAS-987 for data on performance improvements.
  • allowMultipleAccounts - Allows more than one account to be returned.
  • maxNumberOfResults - this is the maximum number of results we allow.
  • scope - One of the predefined "SearchControl" Scopes: SearchControls.OBJECT_SCOPE, SearchControls.ONELEVEL_SCOPE, or SearchControls.SUBTREE_SCOPE
  • searchBase - The search base is the node in the directory from where the search will be performed. (See LDAP Authentication with Multiple Search Bases if, well, you want to use more than one search base.)
  • timeout - This is the amount of time we are willing to wait for the search results to return.

Configuration

Note that all configuration should happen in cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml

Define a ContextSource

BindLdapAuthenticationHandler and FastBindLdapAuthenticationHandler require a Spring ContextSource to provide an LDAP connection on which to perform authentication operations.

SSL Considerations

Icon
  • Make sure LDAP is connecting over SSL by using the ldaps protocol in the url above. The default ldaps port is 636. Failing to do so will generate LDAP authentication exceptions with the error code 49.
  • Please note that the JVM needs to trust the certificate of your SSL enabled LDAP server, else CAS will refuse to connect to your LDAP server. You can add the LDAP server's certificate to the JVM trust store ($JAVA_HOME/jre/lib/security/cacerts by default) to solve that issue.JVM will throw "unable to find valid certification path to requested target" exception when it doesn't find certificate sent by ldap server into keystore. There is a nice open source utility called InstallCert.java available from Sun which can add certificate returned by ldap server into your JVM keystore, use that to solve this problem.

Connection Pooling

The use of PoolingContextSource is strongly recommended in cases where it is supported. This component uses commons-pool object pooling and has performance characteristics suitable for HA environments. This is in stark contrast to the JNDI pooling feature enabled by com.sun.jndi.ldap.connect.pool=true that uses a strategy that will incur unacceptable latency in the case of LDAP node failure.

Connection pooling is supported for BindLdapAuthenticationHandler as of CAS 3.4.9. The searchContextSource property of BindLdapAuthenticationHandler may reference a ContextSource other than the one used for binds and is an ideal opportunity to leverage LDAP connection pooling for improved performance.

Sample Pooled ContextSource

The following property values should serve as a reasonable starting point for pool tuning. They could simply be put into your cas.properties file alongside other property values. 

Sample Pool Configuration Properties

Practical Examples

BindLdapAuthenticationHandler without Pooling
BindLdapAuthenticationHandler with Pooling (3.4.9 and Above)
Typical Active Directory Configuration
Integration with authenticationManager Bean in deployerConfigContext.xml
DIGEST-MD5 Configuration

LDAP Attributes

There are cases where it is necessary to pull additional LDAP attributes (Eg. "mail") into the CAS principal (ie. user object). Please see Attributesfor more on this.
One such application is described in Google Apps from MS-AD using the 'mail' attribute

  • No labels