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 (the same options as the above INI
representation):
Array
(
[server2] => Array
(
[host] => dc1.w.net
[useStartTls] => 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 a number of options associated with retrieving the DN for a username being authenticated.
What is a Distinguished Name?
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 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 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.