Zend_Auth_Adapter_Ldap Operator's Guide

This page describes the Zend_Auth_Adapter_Ldap class for performaing LDAP based authentication. Also described is the zf-ldap demo application used to exercise the adapter. The Zend_Ldap and Zend_Ldap_Exception classes will also be referenced as they perform the bulk of the work including binding and username canonicalization.

The Zend_Auth_Adapter_Ldap Proposal This work has been submitted for inclusion in Zend Framework. See the Zend_Auth_Adapter_Ldap proposal page for details (not to be confused with the old proposal).

Installation

This adapter is available in the incubator subdirectory in SVN. See the Anonymous Checkout and Using the Zend Framework Incubator Components sections at the below link for details:

http://framework.zend.com/wiki/display/ZFDEV/Subversion+Standards

This guide also references a demo application in the zf-ldap package available at http://www.ioplex.com/code/. The simple Zend_Controller based application provides a login form and index page that prints the authenticated user's identity and any result messages. The zf-ldap package also contains the aforementioned LDAP classes although they are not current compared to SVN and will not be updated regularly.

To install the zf-ldap package, unpack it, export the html directory through your web server and adjust html/.htaccess or do what is necessary for your web server to execute a Zend_Controller based application. See the Zend_Controller documentation for details regarding setting up and running a Zend_Controller application.

Usage

To incorporate Zend_Auth_Adapter_Ldap authentication into your application quickly, just copy the demo application's application/controllers/UserController.php code. Even if you're not using Zend_Controller, the meat of your code should look something like the following:

$username = $this->_request->getParam('username');
$password = $this->_request->getParam('password');

$auth = Zend_Auth::getInstance();

require_once('Zend/Config/Ini.php');
$config = new Zend_Config_Ini('../application/config/config.ini', 'production');
$log_path = $config->ldap->log_path;
$options = $config->ldap->toArray();
unset($options['log_path']);

require_once 'Zend/Auth/Adapter/Ldap.php';
$adapter = new Zend_Auth_Adapter_Ldap($options, $username, $password);

$result = $auth->authenticate($adapter);

if ($log_path) {
    $messages = $result->getMessages();

    require_once 'Zend/Log.php';
    require_once 'Zend/Log/Writer/Stream.php';
    require_once 'Zend/Log/Filter/Priority.php';
    $logger = new Zend_Log();
    $logger->addWriter(new Zend_Log_Writer_Stream($log_path));
    $filter = new Zend_Log_Filter_Priority(Zend_Log::DEBUG);
    $logger->addFilter($filter);

    foreach ($messages as $i => $message) {
        if ($i-- > 1) { // $messages[2] and up are log messages
            $message = str_replace("\n", "\n  ", $message);
            $logger->log("Ldap: $i: $message", Zend_Log::DEBUG);
        }
    }
}

Of course the logging code is optional but it is highly recommended that you use a logger. Zend_Auth_Adapter_Ldap will record just about every bit of information anyone could want in $messages (more below) which is a nice feature in itself for something that has a history of being notoriously difficult to debug.

The Zend_Config_Ini code is used above to load the adapter options. It is also optional. A regular array would work equally well. The following is an example application/config/config.ini file that has options for two separate servers. With multiple sets of server options the adapter will try each in-order until the credentials are successfully authenticated. The names of the servers (e.g. server1 and server2) are largely arbitrary. For details regarding the options array, see the Server Options section below. Note that Zend_Config_Ini requires that any values with equals characters (=) will need to be quoted (like the DNs shown below).

[production]

ldap.log_path = /tmp/ldap.log

; Typical options for OpenLDAP
ldap.server1.host = s0.foo.net
ldap.server1.accountDomainName = foo.net 
ldap.server1.accountDomainNameShort = FOO
ldap.server1.accountCanonicalForm = 3
ldap.server1.username = "CN=user1,DC=foo,DC=net"
ldap.server1.password = pass1 
ldap.server1.baseDn = "OU=Sales,DC=foo,DC=net"
ldap.server1.bindRequiresDn = true

; Typical options for Active Directory
ldap.server2.host = dc1.w.net
ldap.server2.useSsl = true
ldap.server2.accountDomainName = w.net 
ldap.server2.accountDomainNameShort = W
ldap.server2.accountCanonicalForm = 3
ldap.server2.baseDn = "CN=Users,DC=w,DC=net"

The above configuration will instruct Zend_Auth_Adapter_Ldap to attempt to authenticate users with the OpenLDAP server s0.foo.net first. If the authentication fails for any reason, the AD server dc1.w.net will be tried.

With servers in different domains, this configuration illustrates multi-domain authentication. You can also have multiple servers in the same domain to provide redundancy.

Note that in this case, even though OpenLDAP has no need for the short NetBIOS style domain name used by Windows we provide it here for name canonicalization purposes (described in the Username Canonicalization section below).

The API

The Zend_Auth_Adapter_Ldap constructor accepts three parameters.

The $options parameter is required and must be an array containing one or more sets of options. Note that it is an array of arrays of Zend_Ldap options. Even if you will be using only one LDAP server, the options must still be within another array.

Below is print_r output of an example options parameter containing two sets of server options for LDAP servers s0.foo.net and dc1.w.net (same options as the above INI representation):

Array
(
    [server2] => Array
        (
            [host] => dc1.w.net
            [useSsl] => 1
            [accountDomainName] => w.net
            [accountDomainNameShort] => W
            [accountCanonicalForm] => 3
            [baseDn] => CN=Users,DC=w,DC=net
        )

    [server1] => Array
        (
            [host] => s0.foo.net
            [accountDomainName] => foo.net
            [accountDomainNameShort] => FOO
            [accountCanonicalForm] => 3
            [username] => CN=user1,DC=foo,DC=net
            [password] => pass1
            [baseDn] => OU=Sales,DC=foo,DC=net
            [bindRequiresDn] => 1
        )

)

The information provided in each set of options above is different mainly because AD does not require a username be in DN form when binding (see the bindRequiresDn option in the Server Options section below) which means we can omit the a number of options associated with retrieving the DN for a username being authenticated.

What is a DN? A DN or "distinguished name" is a string that represents the path to an object within the LDAP directory. Each comma separated component is an attribute and value representing a node. The components are evaluated in reverse. For example, the user account CN=Bob Carter,CN=Users,DC=w,DC=net is located directly within the CN=Users,DC=w,DC=net container. This structure is best explored with an LDAP browser like the ADSI Edit MMC snap-in for Active Directory or phpLDAPadmin.

The names of servers (e.g. 'server1' and 'server2' shown above) are largely arbitrary but for the sake of using Zend_Config the identifiers should be present (as opposed to being numeric indexes) and should not contain any special characters used by the associated file formats (e.g. the '.' INI property separator, '&' for XML entity references, etc).

With multiple sets of server options, the adapter can authenticate users in multiple domains and provide failover so that if one server is not available, another will be queried.

The Gory Details - What exactly happens in the authenticate method? When the authenticate() method is called, the adapter iterates over each set of server options, sets them on the internal Zend_Ldap instance and calls the Zend_Ldap::bind() method with the username and password being authenticated. The Zend_Ldap class checks to see if the username is qualified with a domain (e.g. has a domain component like alice@foo.net or FOO\alice). If a domain is present but it does not match either of the server's domain names (foo.net or FOO), a special exception is thrown and caught by Zend_Auth_Adapter_Ldap that causes that server to be ignored and the next set of server options is selected. If a domain does match, or if the user did not supply a qualified username, Zend_Ldap proceeds to try to bind with the supplied credentials. If the bind is not successful, Zend_Ldap throws a Zend_Ldap_Exception which is caught by Zend_Auth_Adapter_Ldap and the next set of server options is tried. If the bind is successful, the iteration stops and the adapter's authenticate() method returns success. If all server options have been tried without success, the authentication fails and authenticate() returns a failure result with error messages from the last iteration.

The username and password parameters of the Zend_Auth_Adapter_Ldap constructor represent the credentials being authenticated (i.e. the credentials supplied by the user through your HTML login form). Alternatively they may also be set with the setUsername() and setPassword() methods.

Server Options

Each set of server options in the context of Zend_Auth_Adapter_Ldap must consist of the following. Options are passed largely unmodifed to Zend_Ldap::setOptions().

If you enable useSsl = true you may find that the LDAP client may generate an error claiming that it cannot validate the server's certificate. Assuming the PHP LDAP extension is ultimately linked to the OpenLDAP client libraries, to resolve this issue you can set TLS_REQCERT never in the OpenLDAP client ldap.conf (and restart the web server) to indicate to the OpenLDAP client library that you trust the server. Alternatively if you are concerned that the server could be spoofed (not usually the weakest link in an IntrAnet environment) you can export the LDAP server's root certificate and put it on the web server so that the OpenLDAP client can validate the server's identity.

Collecting Debugging Messages

Zend_Auth_Adapter_Ldap collects debugging information within it's authenticate() method. This information is stored in the Zend_Auth_Result object as messages. The array returned by Zend_Auth_Result::getMessages() is described as follows.

In practice index 0 should be displayed to the user (e.g. using the FlashMessenger helper), index 1 should be logged and, if debugging information is being collected, indexes 2 and higher could be logged as well (although the final message always includes the string from index 1).

Common Options for Specific Servers

Options for Active Directory

For ADS, the following options are noteworthy:

[1] Technically there should be no danger of accidental cross-domain authentication with the current Zend_Auth_Adapter_Ldap implementation since server domains are explicitly checked but this may not be true of a future implementation that discovers the domain at runtime or if an alternative adapter is used (e.g. Kerberos). In general, account name ambiguity is known to be the source of security issues so always try to use qualified account names.

Options for OpenLDAP

For OpenLDAP or a generic LDAP server using a typical posixAccount style schema, the following options are noteworthy:

Obtaining a Network Packet Capture on the Web Server

This section describes how to obtain a network packet capture used by Zend_Ldap developers to diagnose failures. Note that all captures must be taken from a machine with access to LDAP traffic between the web server running the Zend_Ldap code and the directory server (e.g. the web server).

Sensitive Information Packet captures must be obtained with useSsl=false which means passwords supplied to the authentication adapter will be captured in the capture file. You may prefer to use a temporary account or change your password before sharing the capture file with anyone. In general, network capture files can contain sensitive information about your network and users and should not be shared with people that you do not trust.

Obtaining a Packet Capture on Linux

Install the tcpdump program on the Linux web server. Make sure useSsl=false and run tcpdump as follows:

Try the operation of interest to provoke the behavior being diagnosed. Press Ctrl-C to stop the capture. Try not to run the capture for too long as it may collect unwanted traffic. This should produce an out.pcap file in the current directory.

Obtaining a Packet Capture on Windows

For a Windows web server, install the XP Support Tools from CD-ROM as described in the following KB article:

http://support.microsoft.com/kb/306794/EN-US/

Run cmd.exe and then netcap.exe /? to see if it was installed properly.

If you have multiple network interfaces look at the end of the output of netcap.exe for the list of adapters. If the one your LDAP traffic is on is not primary, you will need to specify /N:<number> where number is the numeric value for that adapter so make a note of that value.

Now run netcap.exe again as illustrated here (adding the /N:<number> if you need to specify a particular adapter):

This will start to write network packets to the named file out.cap in the current directory. Now try the Zend_Ldap authentication adapter and press the space bar in the cmd.exe window to stop the capture. Try not to allow the capture to run for too long as it may collect unwanted traffic.

The above procedure may also work for other versions of Windows. If you have NetMon installed you may use that as well.