PHP5

Zend_Auth_Adapter_Ldap supports web application authentication with LDAP services. Its features include username and domain name canonicalization, multi-domain authentication, and failover capabilities. It has been tested to work with Microsoft Active Directory and OpenLDAP, but it should also work with other LDAP service providers.

This documentation includes a guide on using Zend_Auth_Adapter_Ldap, an exploration of its API, an outline of the various available options, diagnostic information for troubleshooting authentication problems, and example options for both Active Directory and OpenLDAP servers.

To incorporate Zend_Auth_Adapter_Ldap authentication into your application quickly, even if you're not using Zend_Controller, the meat of your code should look something like the following:

<?php
$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 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 a successful result. 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.

Each set of server options in the context of Zend_Auth_Adapter_Ldap consists of the following options, which are passed, largely unmodifed, to Zend_Ldap::setOptions():

Замечание

If you enable useSsl = true you may find that the LDAP client generates 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, 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.

Zend_Auth_Adapter_Ldap collects debugging information within its 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).