Zend_Auth_Adapter_Ldap 用 LDAP 服务支持 web 程序认证。它的功能包括用户名和域名规范化、多域认证和实效切（failover）换能力。经测试，它能与 » Microsoft Active Directory 和 » OpenLDAP 一起工作，它也应该能和其它 LDAP 服务提供者一起工作。

本文档包括使用 Zend_Auth_Adapter_Ldap 的指南、它的 API 、各种可用选项的大纲、认证问题故障排除的诊断信息和Active Directory 与 OpenLDAP 服务器的范例选项。

为了快速把 Zend_Auth_Adapter_Ldap 认证集成到你的程序中，即使你不使用 Zend_Controller，代码的基本部分看起来是这样的：

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

$auth = Zend_Auth::getInstance();

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

$adapter = new Zend_Auth_Adapter_Ldap($options, $username,
                                      $password);

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

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

    $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);
        }
    }
}

            

上面用到 Zend_Config_Ini 的代码是来加载适配器选项，它也是可选的，使用一个规则的数组来完成工作。下面是带有两个单独的服务器选项的 application/config/config.ini 文件的例子。带有多组服务器选项的适配器将按顺序来尝试每个服务器直到资格被成功认证。服务器的名字 （例如 server1 and server2）是任意的，关于选项数组的细节，参见下面 Server Options 一节。 注意 Zend_Config_Ini 要求任何带有等号（=）的值需要括起来（如下面的 DNs）。

[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"

这个配置示例了在不同的域的服务器的多域认证，也可以在同一域中用多个服务器来提供冗余。

注意在这个例子中，即使 OpenLDAP 不需要用于 Windows 的短 NetBIOS 风格的域名，我们仍在这里提供它以保证命名正规化 （参见下面的 Username Canonicalization 一节）。

Zend_Auth_Adapter_Ldap 构造器接受三个参数。

$options 参数是必需的并且是一个包含一组或多组选项的数组。注意它是 Zend_Ldap 选项的 数组的数组 。即使你只使用一个 LDAP 服务器，选项仍要包含在另一个数组中。

下面是一个选项参数包含两组服务器选项（ s0.foo.net 和 dc1.w.net （和上面 INI 表示法一样的选项））的例子的 » print_r() 输出：

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
        )

)

Note: 什么是 DN?
DN 或者 "distinguished name" 是一个字符串，表示在 LDAP 目录中到一个对象的路径。每个用逗号分隔的组件是一个属性并且它的值表示一个节点。组件是按反顺序来算的，例如：用户账户 CN=Bob Carter,CN=Users,DC=w,DC=net 直接位于 CN=Users,DC=w,DC=net container 里的。这种结构用 LDAP 浏览器如 ADSI Edit MMC snap-in for Active Directory 或 phpLDAPadmin 可以最好地浏览。

服务器名（如上面的 'server1' 和 'server2'）是任意的，但因为使用 Zend_Config，标识符（identifiers）应当以数字索引的相反出现并且不应当包含任何用于相关文件格式（例如，'.' INI 属性分隔符，XML 条目参考 '&' 等）的特殊字符。

用多组服务器选项，适配器可以在多域的环境中认证用户并提供 failover （估计是失败后尝试下一个服务器），所以如果一个服务器不可用，将查询另一个。

Note: 非常详细的介绍 （The Gory Details）－ 在认证方法中到底发生了什么？
当调用 authenticate() 方法，适配器反复把每组服务器选项设置到内部 Zend_Ldap 实例并带用于认证的用户名和密码调用 Zend_Ldap::bind() 方法。Zend_Ldap 类检查用户名是否在域中合格 （例如，有域的组件如 alice@foo.net 或 FOO\alice）。如果域存在，但它不匹配任何一种服务器的域名（foo.net 或 FOO），就抛出一个特殊的异常并由 Zend_Auth_Adapter_Ldap 捕捉，这样那个服务器就被忽略并且选择下个服务器选项。如果域名 确实 匹配，但是如果用户没有提供一个合格的用户名，Zend_Ldap 继续尝试绑定被提供的证书（credentials）。如果绑定不成功，Zend_Ldap 抛出一个由 Zend_Auth_Adapter_Ldap 捕捉的 Zend_Ldap_Exception 并尝试下一组服务器选项。如果绑定成功，反复尝试（迭代？(iteration)）就停止，并且适配器的 authenticate() 方法返回一个成功的结果。如果所有服务器选项都试过了而且都不成功，认证就失败了，authenticate() 返回一个失败的结果并带有最后一个尝试的错误消息。

Zend_Auth_Adapter_Ldap 构造器的用户名和密码参数是要被认证的证书（例如，用户通过 HTML 登录表单提供的证书（credentials））。另外，也可以通过 setUsername() 和 setPassword() 方法来设置。

在 Zend_Auth_Adapter_Ldap 的上下文中 的每组服务器选项包含下列选项，它们基本上不可修改地传递给 Zend_Ldap::setOptions()：

Note: 如果你设置 useSsl = true 可能发现 LDAP 客户端会产生一个不能校验服务器证书的错误。假定 PHP LDAP 扩展完全链接到 OpenLDAP 客户库，为解决这个问题你可以在 OpenLDAP 客户 ldap.conf 里设置 “TLS_REQCERT never” （并重启 web 服务器）来指明 OpenLDAP 客户端库你信任这个服务器。另外如果涉及到服务器可能被欺骗，你可以输出 LDAP 服务器的根证书并把它放到 web 服务器，这样 OpenLDAP 客户端可以校验服务器的身份。

Zend_Auth_Adapter_Ldap 在它的 authenticate() 方法里收集调试信息。这个信息存储在 Zend_Auth_Result 对象里。下面描述由 Zend_Auth_Result::getMessages() 返回的数组：