Each set of server options in the context of
Zend_Auth_Adapter_Ldap consists of the following
options, which are passed, largely unmodified, to
Zend_Ldap::setOptions():
Table 10. Server Options
| Name | Description |
|---|---|
| host | The hostname of LDAP server that these options represent. This option is required. |
| port |
The port on which the LDAP server is listening. If
useSsl is TRUE, the default
port value is 636. If useSsl
is FALSE, the default port
value is 389.
|
| useStartTls |
Whether or not the LDAP client should use
TLS (aka SSLv2) encrypted
transport. A value of TRUE is strongly favored in
production environments to prevent passwords from be transmitted in
clear text. The default value is FALSE, as servers
frequently require that a certificate be installed separately after
installation. The useSsl and
useStartTls options are mutually exclusive. The
useStartTls option should be favored over
useSsl but not all servers support this newer
mechanism.
|
| useSsl | Whether or not the LDAP client should use SSL encrypted transport. The useSsl and useStartTls options are mutually exclusive, but useStartTls should be favored if the server and LDAP client library support it. This value also changes the default port value (see port description above). |
| username |
The DN of the account used to perform account DN lookups.
LDAP servers that require the username to be in DN
form when performing the "bind" require this option. Meaning, if
bindRequiresDn is TRUE, this
option is required. This account does not need to be a privileged
account; an account with read-only access to objects under the
baseDn is all that is necessary (and preferred
based on the Principle of Least Privilege).
|
| password | The password of the account used to perform account DN lookups. If this option is not supplied, the LDAP client will attempt an "anonymous bind" when performing account DN lookups. |
| bindRequiresDn |
Some LDAP servers require that the username used to
bind be in DN form like
CN=Alice Baker,OU=Sales,DC=foo,DC=net (basically
all servers except AD). If this option is
TRUE, this instructs
Zend_Ldap to automatically retrieve the DN
corresponding to the username being authenticated, if it is not already
in DN form, and then re-bind with the proper DN. The default value is
FALSE. Currently only Microsoft Active Directory
Server (ADS) is known not to
require usernames to be in DN form when binding, and therefore this
option may be FALSE with AD (and it should be, as
retrieving the DN requires an extra round trip to the server).
Otherwise, this option must be set to TRUE (e.g.
for OpenLDAP). This option also controls the default
acountFilterFormat used when searching for
accounts. See the accountFilterFormat option.
|
| baseDn |
The DN under which all accounts being authenticated are located. This
option is required. if you are uncertain about the correct
baseDn value, it should be sufficient to derive it
from the user's DNS domain using
DC= components. For example, if the user's
principal name is alice@foo.net, a
baseDn of DC=foo,DC=net
should work. A more precise location (e.g.,
OU=Sales,DC=foo,DC=net) will be more efficient,
however.
|
| accountCanonicalForm |
A value of 2, 3 or 4 indicating the form to which account names should
be canonicalized after successful authentication. Values are as
follows: 2 for traditional username style names (e.g.,
alice), 3 for backslash-style names (e.g.,
FOO\alice) or 4 for principal style usernames
(e.g., alice@foo.net). The default value is 4
(e.g., alice@foo.net). For example, with a value
of 3, the identity returned by
Zend_Auth_Result::getIdentity() (and
Zend_Auth::getIdentity(), if
Zend_Auth was used) will always be
FOO\alice, regardless of what form Alice supplied,
whether it be alice,
alice@foo.net, FOO\alice,
FoO\aLicE, foo.net\alice,
etc. See the Account Name Canonicalization section
in the Zend_Ldap documentation for details. Note
that when using multiple sets of server options it is recommended, but
not required, that the same accountCanonicalForm
be used with all server options so that the resulting usernames are
always canonicalized to the same form (e.g., if you canonicalize to
EXAMPLE\username with an AD server but to
username@example.com with an OpenLDAP server, that
may be awkward for the application's high-level logic).
|
| accountDomainName |
The FQDN domain name for which the target
LDAP server is an authority (e.g.,
example.com). This option is used to canonicalize
names so that the username supplied by the user can be converted as
necessary for binding. It is also used to determine if the server is an
authority for the supplied username (e.g., if
accountDomainName is foo.net
and the user supplies bob@bar.net, the server will
not be queried, and a failure will result). This option is not
required, but if it is not supplied, usernames in principal name form
(e.g., alice@foo.net) are not supported. It is
strongly recommended that you supply this option, as there are many
use-cases that require generating the principal name form.
|
| accountDomainNameShort |
The 'short' domain for which the target LDAP server
is an authority (e.g., FOO). Note that there is a
1:1 mapping between the accountDomainName and
accountDomainNameShort. This option should be used
to specify the NetBIOS domain name for Windows networks, but may also
be used by non-AD servers (e.g., for consistency when multiple sets of
server options with the backslash style
accountCanonicalForm). This option is not required
but if it is not supplied, usernames in backslash form (e.g.,
FOO\alice) are not supported.
|
| accountFilterFormat |
The LDAP search filter used to search for accounts.
This string is a printf()-style
expression that must contain one '%s' to
accomodate the username. The default value is
'(&(objectClass=user)(sAMAccountName=%s))',
unless bindRequiresDn is set to
TRUE, in which case the default is
'(&(objectClass=posixAccount)(uid=%s))'. For
example, if for some reason you wanted to use
bindRequiresDn = true with AD you would need to
set accountFilterFormat =
'(&(objectClass=user)(sAMAccountName=%s))'.
|
| optReferrals |
If set to TRUE, this option indicates to the
LDAP client that referrals should be followed. The
default value is FALSE.
|
Note
If you enable useStartTls = TRUE or
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.