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

            

虽然日志（ logging ）代码是可选的，还是强烈建议使用日志。Zend_Auth_Adapter_Ldap 将记录任何想要的信息细节到 $messages （更多的信息看下面），对于难以调试的程序来说，有历史记录这是个很好的功能。

上面用到 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"

上述的配置将指示 Zend_Auth_Adapter_Ldap 首先来尝试用 OpenLDAP 服务器 s0.foo.net 来认证用户，如果不论什么原因认证失败，将尝试 AD 服务器 dc1.w.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
        )

)

上述每组选项提供的信息是不同的，主要是因为当绑定（参见下面 服务器选项 一节中的 bindRequiresDn 选项）时 AD 不要求在 DN 表单中的有用户名，这意味着我们可以忽略很多和为认证用户名获取 DN 相关的选项。

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

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

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

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

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

实践上，index 0 显示给用户（例如使用 FlashMessenger 助手）， index 1 作为日志，如果收集到调试信息， index 2 和它以后的 index 也作为日志（尽管最终的信息总是从 index 1 的字符串开始）。