|
@@ -9,17 +9,19 @@
|
|
|
<title>Introduction</title>
|
|
<title>Introduction</title>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- <classname>Zend_Auth_Adapter_Ldap</classname> 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
|
|
|
|
|
- <ulink url="http://www.microsoft.com/windowsserver2003/technologies/directory/activedirectory/">Microsoft
|
|
|
|
|
- Active Directory</ulink> and <ulink url="http://www.openldap.org/">OpenLDAP</ulink>, but it should also
|
|
|
|
|
- work with other LDAP service providers.
|
|
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname> 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
|
|
|
|
|
+ <ulink
|
|
|
|
|
+ url="http://www.microsoft.com/windowsserver2003/technologies/directory/activedirectory/">Microsoft
|
|
|
|
|
+ Active Directory</ulink> and <ulink url="http://www.openldap.org/">OpenLDAP</ulink>,
|
|
|
|
|
+ but it should also work with other LDAP service providers.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- This documentation includes a guide on using <classname>Zend_Auth_Adapter_Ldap</classname>, an exploration of its
|
|
|
|
|
- API, an outline of the various available options, diagnostic information for troubleshooting authentication
|
|
|
|
|
|
|
+ This documentation includes a guide on using
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname>, 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.
|
|
problems, and example options for both Active Directory and OpenLDAP servers.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
@@ -30,9 +32,9 @@
|
|
|
<title>Usage</title>
|
|
<title>Usage</title>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- To incorporate <classname>Zend_Auth_Adapter_Ldap</classname> authentication into your application quickly, even if
|
|
|
|
|
- you're not using <classname>Zend_Controller</classname>, the meat of your code should look something like the
|
|
|
|
|
- following:
|
|
|
|
|
|
|
+ To incorporate <classname>Zend_Auth_Adapter_Ldap</classname> authentication into your
|
|
|
|
|
+ application quickly, even if you're not using <classname>Zend_Controller</classname>,
|
|
|
|
|
+ the meat of your code should look something like the following:
|
|
|
<programlisting language="php"><![CDATA[
|
|
<programlisting language="php"><![CDATA[
|
|
|
$username = $this->_request->getParam('username');
|
|
$username = $this->_request->getParam('username');
|
|
|
$password = $this->_request->getParam('password');
|
|
$password = $this->_request->getParam('password');
|
|
@@ -66,20 +68,22 @@ if ($log_path) {
|
|
|
}
|
|
}
|
|
|
}
|
|
}
|
|
|
]]></programlisting>
|
|
]]></programlisting>
|
|
|
- Of course, the logging code is optional, but it is highly recommended that you use a logger.
|
|
|
|
|
- <classname>Zend_Auth_Adapter_Ldap</classname> will record just about every bit of information anyone could want in
|
|
|
|
|
- <varname>$messages</varname> (more below), which is a nice feature in itself for something that has a history of
|
|
|
|
|
- being notoriously difficult to debug.
|
|
|
|
|
|
|
+ Of course, the logging code is optional, but it is highly recommended that you use a
|
|
|
|
|
+ logger. <classname>Zend_Auth_Adapter_Ldap</classname> will record just about every bit
|
|
|
|
|
+ of information anyone could want in <varname>$messages</varname> (more below), which is
|
|
|
|
|
+ a nice feature in itself for something that has a history of being notoriously difficult
|
|
|
|
|
+ to debug.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- The <classname>Zend_Config_Ini</classname> 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
|
|
|
|
|
- <filename>application/config/config.ini</filename> 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 <emphasis>Server Options</emphasis> section
|
|
|
|
|
- below. Note that <classname>Zend_Config_Ini</classname> requires that any values with "equals" characters
|
|
|
|
|
|
|
+ The <classname>Zend_Config_Ini</classname> 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 <filename>application/config/config.ini</filename> 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 <emphasis>Server Options</emphasis> section below. Note that
|
|
|
|
|
+ <classname>Zend_Config_Ini</classname> requires that any values with "equals" characters
|
|
|
(<emphasis>=</emphasis>) will need to be quoted (like the DNs shown below).
|
|
(<emphasis>=</emphasis>) will need to be quoted (like the DNs shown below).
|
|
|
<programlisting language="ini"><![CDATA[
|
|
<programlisting language="ini"><![CDATA[
|
|
|
[production]
|
|
[production]
|
|
@@ -104,20 +108,22 @@ ldap.server2.accountDomainNameShort = W
|
|
|
ldap.server2.accountCanonicalForm = 3
|
|
ldap.server2.accountCanonicalForm = 3
|
|
|
ldap.server2.baseDn = "CN=Users,DC=w,DC=net"
|
|
ldap.server2.baseDn = "CN=Users,DC=w,DC=net"
|
|
|
]]></programlisting>
|
|
]]></programlisting>
|
|
|
- The above configuration will instruct <classname>Zend_Auth_Adapter_Ldap</classname> to attempt to authenticate users
|
|
|
|
|
- with the OpenLDAP server <filename>s0.foo.net</filename> first. If the authentication fails for any reason, the AD
|
|
|
|
|
- server <filename>dc1.w.net</filename> will be tried.
|
|
|
|
|
|
|
+ The above configuration will instruct <classname>Zend_Auth_Adapter_Ldap</classname> to
|
|
|
|
|
+ attempt to authenticate users with the OpenLDAP server <filename>s0.foo.net</filename>
|
|
|
|
|
+ first. If the authentication fails for any reason, the AD server
|
|
|
|
|
+ <filename>dc1.w.net</filename> will be tried.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- With servers in different domains, this configuration illustrates multi-domain authentication. You can also
|
|
|
|
|
- have multiple servers in the same domain to provide redundancy.
|
|
|
|
|
|
|
+ With servers in different domains, this configuration illustrates multi-domain
|
|
|
|
|
+ authentication. You can also have multiple servers in the same domain to provide
|
|
|
|
|
+ redundancy.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- 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
|
|
|
|
|
- <emphasis>Username Canonicalization</emphasis> section below).
|
|
|
|
|
|
|
+ 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 <emphasis>Username Canonicalization</emphasis> section below).
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
</sect2>
|
|
</sect2>
|
|
@@ -131,16 +137,17 @@ ldap.server2.baseDn = "CN=Users,DC=w,DC=net"
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- The <varname>$options</varname> parameter is required and must be an array containing one or more sets of
|
|
|
|
|
- options. Note that it is <emphasis>an array of arrays</emphasis> of
|
|
|
|
|
- <link linkend="zend.ldap"><classname>Zend_Ldap</classname></link> options. Even if you will be using only one LDAP server, the
|
|
|
|
|
- options must still be within another array.
|
|
|
|
|
|
|
+ The <varname>$options</varname> parameter is required and must be an array containing
|
|
|
|
|
+ one or more sets of options. Note that it is <emphasis>an array of arrays</emphasis> of
|
|
|
|
|
+ <link linkend="zend.ldap"><classname>Zend_Ldap</classname></link> options. Even if you
|
|
|
|
|
+ will be using only one LDAP server, the options must still be within another array.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- Below is <ulink url="http://php.net/print_r"><methodname>print_r()</methodname></ulink> output of an example options
|
|
|
|
|
- parameter containing two sets of server options for LDAP servers <filename>s0.foo.net</filename> and
|
|
|
|
|
- <filename>dc1.w.net</filename> (the same options as the above INI representation):
|
|
|
|
|
|
|
+ Below is <ulink url="http://php.net/print_r"><methodname>print_r()</methodname></ulink>
|
|
|
|
|
+ output of an example options parameter containing two sets of server options for LDAP
|
|
|
|
|
+ servers <filename>s0.foo.net</filename> and <filename>dc1.w.net</filename> (the same
|
|
|
|
|
+ options as the above INI representation):
|
|
|
<programlisting language="output"><![CDATA[
|
|
<programlisting language="output"><![CDATA[
|
|
|
Array
|
|
Array
|
|
|
(
|
|
(
|
|
@@ -168,62 +175,73 @@ Array
|
|
|
|
|
|
|
|
)
|
|
)
|
|
|
]]></programlisting>
|
|
]]></programlisting>
|
|
|
- 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 <emphasis>bindRequiresDn</emphasis> option in the
|
|
|
|
|
- <emphasis>Server Options</emphasis> section below), which means we can omit a number of options
|
|
|
|
|
- associated with retrieving the DN for a username being authenticated.
|
|
|
|
|
|
|
+ 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
|
|
|
|
|
+ <emphasis>bindRequiresDn</emphasis> option in the <emphasis>Server Options</emphasis>
|
|
|
|
|
+ section below), which means we can omit a number of options associated with retrieving
|
|
|
|
|
+ the DN for a username being authenticated.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
<note>
|
|
|
<title>What is a Distinguished Name?</title>
|
|
<title>What is a Distinguished Name?</title>
|
|
|
<para>
|
|
<para>
|
|
|
- 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
|
|
|
|
|
- <emphasis>CN=Bob Carter,CN=Users,DC=w,DC=net</emphasis> is located directly within the
|
|
|
|
|
- <emphasis>CN=Users,DC=w,DC=net container</emphasis>. This structure is best explored with an LDAP
|
|
|
|
|
- browser like the ADSI Edit MMC snap-in for Active Directory or phpLDAPadmin.
|
|
|
|
|
|
|
+ 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 <emphasis>CN=Bob Carter,CN=Users,DC=w,DC=net</emphasis> is located directly
|
|
|
|
|
+ within the <emphasis>CN=Users,DC=w,DC=net container</emphasis>. This structure is
|
|
|
|
|
+ best explored with an LDAP browser like the ADSI Edit MMC snap-in for Active
|
|
|
|
|
+ Directory or phpLDAPadmin.
|
|
|
</para>
|
|
</para>
|
|
|
</note>
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- The names of servers (e.g. 'server1' and 'server2' shown above) are largely
|
|
|
|
|
- arbitrary, but for the sake of using <classname>Zend_Config</classname>, 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 '<emphasis>.</emphasis>' INI property separator, '<emphasis>&</emphasis>' for XML entity references,
|
|
|
|
|
- etc).
|
|
|
|
|
|
|
+ The names of servers (e.g. 'server1' and 'server2' shown above) are largely arbitrary,
|
|
|
|
|
+ but for the sake of using <classname>Zend_Config</classname>, 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 '<emphasis>.</emphasis>' INI
|
|
|
|
|
+ property separator, '<emphasis>&</emphasis>' for XML entity references, etc).
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- 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.
|
|
|
|
|
|
|
+ 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.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
<note>
|
|
|
<title>The Gory Details: What Happens in the Authenticate Method?</title>
|
|
<title>The Gory Details: What Happens in the Authenticate Method?</title>
|
|
|
<para>
|
|
<para>
|
|
|
- When the <methodname>authenticate()</methodname> method is called, the adapter iterates over each set of server
|
|
|
|
|
- options, sets them on the internal <classname>Zend_Ldap</classname> instance, and calls the
|
|
|
|
|
- <classname>Zend_Ldap::bind()</classname> method with the username and password being authenticated. The
|
|
|
|
|
- <classname>Zend_Ldap</classname> class checks to see if the username is qualified with a domain (e.g., has a
|
|
|
|
|
- domain component like <emphasis>alice@foo.net</emphasis> or <emphasis>FOO\alice</emphasis>). If a
|
|
|
|
|
- domain is present, but does not match either of the server's domain names
|
|
|
|
|
- (<emphasis>foo.net</emphasis> or <emphasis>FOO</emphasis>), a special exception is thrown and caught by
|
|
|
|
|
- <classname>Zend_Auth_Adapter_Ldap</classname> that causes that server to be ignored and the next set of server
|
|
|
|
|
- options is selected. If a domain <emphasis>does</emphasis> match, or if the user did not supply a
|
|
|
|
|
- qualified username, <classname>Zend_Ldap</classname> proceeds to try to bind with the supplied credentials. If
|
|
|
|
|
- the bind is not successful, <classname>Zend_Ldap</classname> throws a <classname>Zend_Ldap_Exception</classname> which is
|
|
|
|
|
- caught by <classname>Zend_Auth_Adapter_Ldap</classname> and the next set of server options is tried. If the bind
|
|
|
|
|
- is successful, the iteration stops, and the adapter's <methodname>authenticate()</methodname> method returns a
|
|
|
|
|
- successful result. If all server options have been tried without success, the authentication fails, and
|
|
|
|
|
- <methodname>authenticate()</methodname> returns a failure result with error messages from the last iteration.
|
|
|
|
|
|
|
+ When the <methodname>authenticate()</methodname> method is called, the adapter
|
|
|
|
|
+ iterates over each set of server options, sets them on the internal
|
|
|
|
|
+ <classname>Zend_Ldap</classname> instance, and calls the
|
|
|
|
|
+ <classname>Zend_Ldap::bind()</classname> method with the username and password being
|
|
|
|
|
+ authenticated. The <classname>Zend_Ldap</classname> class checks to see if the
|
|
|
|
|
+ username is qualified with a domain (e.g., has a domain component like
|
|
|
|
|
+ <emphasis>alice@foo.net</emphasis> or <emphasis>FOO\alice</emphasis>). If a domain
|
|
|
|
|
+ is present, but does not match either of the server's domain names
|
|
|
|
|
+ (<emphasis>foo.net</emphasis> or <emphasis>FOO</emphasis>), a special exception is
|
|
|
|
|
+ thrown and caught by <classname>Zend_Auth_Adapter_Ldap</classname> that causes that
|
|
|
|
|
+ server to be ignored and the next set of server options is selected. If a domain
|
|
|
|
|
+ <emphasis>does</emphasis> match, or if the user did not supply a qualified username,
|
|
|
|
|
+ <classname>Zend_Ldap</classname> proceeds to try to bind with the supplied
|
|
|
|
|
+ credentials. if the bind is not successful, <classname>Zend_Ldap</classname> throws
|
|
|
|
|
+ a <classname>Zend_Ldap_Exception</classname> which is caught by
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname> and the next set of server options is
|
|
|
|
|
+ tried. If the bind is successful, the iteration stops, and the adapter's
|
|
|
|
|
+ <methodname>authenticate()</methodname> method returns a successful result. If all
|
|
|
|
|
+ server options have been tried without success, the authentication fails, and
|
|
|
|
|
+ <methodname>authenticate()</methodname> returns a failure result with error messages
|
|
|
|
|
+ from the last iteration.
|
|
|
</para>
|
|
</para>
|
|
|
</note>
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- The username and password parameters of the <classname>Zend_Auth_Adapter_Ldap</classname> 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 <methodname>setUsername()</methodname> and <methodname>setPassword()</methodname>
|
|
|
|
|
|
|
+ The username and password parameters of the
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname> 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
|
|
|
|
|
+ <methodname>setUsername()</methodname> and <methodname>setPassword()</methodname>
|
|
|
methods.
|
|
methods.
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
@@ -234,8 +252,10 @@ Array
|
|
|
<title>Server Options</title>
|
|
<title>Server Options</title>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- Each set of server options <emphasis>in the context of <classname>Zend_Auth_Adapter_Ldap</classname></emphasis> consists of the
|
|
|
|
|
- following options, which are passed, largely unmodified, to <classname>Zend_Ldap::setOptions()</classname>:
|
|
|
|
|
|
|
+ Each set of server options <emphasis>in the context of
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname></emphasis> consists of the following
|
|
|
|
|
+ options, which are passed, largely unmodified, to
|
|
|
|
|
+ <classname>Zend_Ldap::setOptions()</classname>:
|
|
|
|
|
|
|
|
<table id="zend.auth.adapter.ldap.server-options.table">
|
|
<table id="zend.auth.adapter.ldap.server-options.table">
|
|
|
<title>Server Options</title>
|
|
<title>Server Options</title>
|
|
@@ -250,123 +270,142 @@ Array
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>host</emphasis></entry>
|
|
<entry><emphasis>host</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The hostname of LDAP server that these options represent. This option is required.
|
|
|
|
|
|
|
+ The hostname of LDAP server that these options represent. This option is
|
|
|
|
|
+ required.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>port</emphasis></entry>
|
|
<entry><emphasis>port</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The port on which the LDAP server is listening. If <emphasis>useSsl</emphasis> is
|
|
|
|
|
- <constant>TRUE</constant>, the default <emphasis>port</emphasis> value is 636. If
|
|
|
|
|
- <emphasis>useSsl</emphasis> is <constant>FALSE</constant>, the default
|
|
|
|
|
- <emphasis>port</emphasis> value is 389.
|
|
|
|
|
|
|
+ The port on which the LDAP server is listening. If
|
|
|
|
|
+ <emphasis>useSsl</emphasis> is <constant>TRUE</constant>, the default
|
|
|
|
|
+ <emphasis>port</emphasis> value is 636. if <emphasis>useSsl</emphasis> is
|
|
|
|
|
+ <constant>FALSE</constant>, the default <emphasis>port</emphasis> value is
|
|
|
|
|
+ 389.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry>useStartTls</entry>
|
|
<entry>useStartTls</entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Whether or not the LDAP client should use TLS (aka SSLv2) encrypted transport. A value of
|
|
|
|
|
- <constant>TRUE</constant> is strongly favored in production environments to prevent passwords from
|
|
|
|
|
- be transmitted in clear text. The default value is <constant>FALSE</constant>, as servers
|
|
|
|
|
- frequently require that a certificate be installed separately after installation.
|
|
|
|
|
- The <emphasis>useSsl</emphasis> and <emphasis>useStartTls</emphasis> options are mutually exclusive.
|
|
|
|
|
- The <emphasis>useStartTls</emphasis> option should be favored over <emphasis>useSsl</emphasis> but
|
|
|
|
|
- not all servers support this newer mechanism.
|
|
|
|
|
|
|
+ Whether or not the LDAP client should use TLS (aka SSLv2) encrypted
|
|
|
|
|
+ transport. A value of <constant>TRUE</constant> is strongly favored in
|
|
|
|
|
+ production environments to prevent passwords from be transmitted in clear
|
|
|
|
|
+ text. The default value is <constant>FALSE</constant>, as servers frequently
|
|
|
|
|
+ require that a certificate be installed separately after installation. The
|
|
|
|
|
+ <emphasis>useSsl</emphasis> and <emphasis>useStartTls</emphasis> options are
|
|
|
|
|
+ mutually exclusive. The <emphasis>useStartTls</emphasis> option should be
|
|
|
|
|
+ favored over <emphasis>useSsl</emphasis> but not all servers support this
|
|
|
|
|
+ newer mechanism.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry>useSsl</entry>
|
|
<entry>useSsl</entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Whether or not the LDAP client should use SSL encrypted transport. The <emphasis>useSsl</emphasis>
|
|
|
|
|
- and <emphasis>useStartTls</emphasis> options are mutually exclusive, but <emphasis>useStartTls</emphasis>
|
|
|
|
|
- should be favored if the server and LDAP client library support it.
|
|
|
|
|
- This value also changes the default <emphasis>port</emphasis> value (see
|
|
|
|
|
- <emphasis>port</emphasis> description above).
|
|
|
|
|
|
|
+ Whether or not the LDAP client should use SSL encrypted transport. The
|
|
|
|
|
+ <emphasis>useSsl</emphasis> and <emphasis>useStartTls</emphasis> options are
|
|
|
|
|
+ mutually exclusive, but <emphasis>useStartTls</emphasis> should be favored
|
|
|
|
|
+ if the server and LDAP client library support it. This value also changes
|
|
|
|
|
+ the default <emphasis>port</emphasis> value (see <emphasis>port</emphasis>
|
|
|
|
|
+ description above).
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>username</emphasis></entry>
|
|
<entry><emphasis>username</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- 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
|
|
|
|
|
- <emphasis>bindRequiresDn</emphasis> is <constant>TRUE</constant>, this option is
|
|
|
|
|
- required. This account does not need to be a privileged account; an account with read-only
|
|
|
|
|
- access to objects under the <emphasis>baseDn</emphasis> is all that is necessary
|
|
|
|
|
- (and preferred based on the <emphasis>Principle of Least Privilege</emphasis>).
|
|
|
|
|
|
|
+ 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 <emphasis>bindRequiresDn</emphasis> is
|
|
|
|
|
+ <constant>TRUE</constant>, this option is required. This account does not
|
|
|
|
|
+ need to be a privileged account; an account with read-only access to objects
|
|
|
|
|
+ under the <emphasis>baseDn</emphasis> is all that is necessary (and
|
|
|
|
|
+ preferred based on the <emphasis>Principle of Least Privilege</emphasis>).
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>password</emphasis></entry>
|
|
<entry><emphasis>password</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- 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.
|
|
|
|
|
|
|
+ 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.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>bindRequiresDn</emphasis></entry>
|
|
<entry><emphasis>bindRequiresDn</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
Some LDAP servers require that the username used to bind be in DN form like
|
|
Some LDAP servers require that the username used to bind be in DN form like
|
|
|
- <emphasis>CN=Alice Baker,OU=Sales,DC=foo,DC=net</emphasis> (basically all servers
|
|
|
|
|
- <emphasis>except</emphasis> AD). If this option is <constant>TRUE</constant>, this instructs
|
|
|
|
|
- <classname>Zend_Ldap</classname> 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 <constant>FALSE</constant>. Currently only Microsoft Active Directory Server (ADS) is
|
|
|
|
|
- known <emphasis>not</emphasis> to require usernames to be in DN form when binding, and
|
|
|
|
|
- therefore this option may be <constant>FALSE</constant> 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
|
|
|
|
|
- <constant>TRUE</constant> (e.g. for OpenLDAP). This option also controls the default
|
|
|
|
|
- <emphasis>acountFilterFormat</emphasis> used when searching for accounts. See the
|
|
|
|
|
- <emphasis>accountFilterFormat</emphasis> option.
|
|
|
|
|
|
|
+ <emphasis>CN=Alice Baker,OU=Sales,DC=foo,DC=net</emphasis> (basically all
|
|
|
|
|
+ servers <emphasis>except</emphasis> AD). If this option is
|
|
|
|
|
+ <constant>TRUE</constant>, this instructs <classname>Zend_Ldap</classname>
|
|
|
|
|
+ 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 <constant>FALSE</constant>. Currently only
|
|
|
|
|
+ Microsoft Active Directory Server (ADS) is known <emphasis>not</emphasis> to
|
|
|
|
|
+ require usernames to be in DN form when binding, and therefore this option
|
|
|
|
|
+ may be <constant>FALSE</constant> 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 <constant>TRUE</constant> (e.g. for OpenLDAP). This option
|
|
|
|
|
+ also controls the default <emphasis>acountFilterFormat</emphasis> used when
|
|
|
|
|
+ searching for accounts. See the <emphasis>accountFilterFormat</emphasis>
|
|
|
|
|
+ option.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The DN under which all accounts being authenticated are located. This option is required. If
|
|
|
|
|
- you are uncertain about the correct <emphasis>baseDn</emphasis> value, it should
|
|
|
|
|
- be sufficient to derive it from the user's DNS domain using <emphasis>DC=</emphasis>
|
|
|
|
|
- components. For example, if the user's principal name is <emphasis>alice@foo.net</emphasis>, a
|
|
|
|
|
- <emphasis>baseDn</emphasis> of <emphasis>DC=foo,DC=net</emphasis> should work. A
|
|
|
|
|
- more precise location (e.g., <emphasis>OU=Sales,DC=foo,DC=net</emphasis>) will be more
|
|
|
|
|
- efficient, however.
|
|
|
|
|
|
|
+ The DN under which all accounts being authenticated are located. This option
|
|
|
|
|
+ is required. if you are uncertain about the correct
|
|
|
|
|
+ <emphasis>baseDn</emphasis> value, it should be sufficient to derive it from
|
|
|
|
|
+ the user's DNS domain using <emphasis>DC=</emphasis> components. For
|
|
|
|
|
+ example, if the user's principal name is <emphasis>alice@foo.net</emphasis>,
|
|
|
|
|
+ a <emphasis>baseDn</emphasis> of <emphasis>DC=foo,DC=net</emphasis> should
|
|
|
|
|
+ work. A more precise location (e.g.,
|
|
|
|
|
+ <emphasis>OU=Sales,DC=foo,DC=net</emphasis>) will be more efficient,
|
|
|
|
|
+ however.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- 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.,
|
|
|
|
|
- <emphasis>alice</emphasis>), 3 for backslash-style names (e.g., <emphasis>FOO\alice</emphasis>)
|
|
|
|
|
- or 4 for principal style usernames (e.g., <emphasis>alice@foo.net</emphasis>). The default
|
|
|
|
|
- value is 4 (e.g., <emphasis>alice@foo.net</emphasis>). For example, with a value of 3, the
|
|
|
|
|
- identity returned by <classname>Zend_Auth_Result::getIdentity()</classname> (and
|
|
|
|
|
- <classname>Zend_Auth::getIdentity()</classname>, if <classname>Zend_Auth</classname> was used) will always be
|
|
|
|
|
- <emphasis>FOO\alice</emphasis>, regardless of what form Alice supplied, whether it be
|
|
|
|
|
- <emphasis>alice</emphasis>, <emphasis>alice@foo.net</emphasis>, <emphasis>FOO\alice</emphasis>,
|
|
|
|
|
- <emphasis>FoO\aLicE</emphasis>, <emphasis>foo.net\alice</emphasis>, etc. See the
|
|
|
|
|
- <emphasis>Account Name Canonicalization</emphasis> section in the <classname>Zend_Ldap</classname>
|
|
|
|
|
- documentation for details. Note that when using multiple sets of server options it is
|
|
|
|
|
- recommended, but not required, that the same
|
|
|
|
|
- <emphasis>accountCanonicalForm</emphasis> be used with all server options so that
|
|
|
|
|
- the resulting usernames are always canonicalized to the same form (e.g., if you canonicalize to
|
|
|
|
|
|
|
+ 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., <emphasis>alice</emphasis>), 3 for
|
|
|
|
|
+ backslash-style names (e.g., <emphasis>FOO\alice</emphasis>) or 4 for
|
|
|
|
|
+ principal style usernames (e.g., <emphasis>alice@foo.net</emphasis>). The
|
|
|
|
|
+ default value is 4 (e.g., <emphasis>alice@foo.net</emphasis>). For example,
|
|
|
|
|
+ with a value of 3, the identity returned by
|
|
|
|
|
+ <classname>Zend_Auth_Result::getIdentity()</classname> (and
|
|
|
|
|
+ <classname>Zend_Auth::getIdentity()</classname>, if
|
|
|
|
|
+ <classname>Zend_Auth</classname> was used) will always be
|
|
|
|
|
+ <emphasis>FOO\alice</emphasis>, regardless of what form Alice supplied,
|
|
|
|
|
+ whether it be <emphasis>alice</emphasis>,
|
|
|
|
|
+ <emphasis>alice@foo.net</emphasis>, <emphasis>FOO\alice</emphasis>,
|
|
|
|
|
+ <emphasis>FoO\aLicE</emphasis>, <emphasis>foo.net\alice</emphasis>, etc. See
|
|
|
|
|
+ the <emphasis>Account Name Canonicalization</emphasis> section in the
|
|
|
|
|
+ <classname>Zend_Ldap</classname> documentation for details. Note that when
|
|
|
|
|
+ using multiple sets of server options it is recommended, but not required,
|
|
|
|
|
+ that the same <emphasis>accountCanonicalForm</emphasis> be used with all
|
|
|
|
|
+ server options so that the resulting usernames are always canonicalized to
|
|
|
|
|
+ the same form (e.g., if you canonicalize to
|
|
|
<emphasis>EXAMPLE\username</emphasis> with an AD server but to
|
|
<emphasis>EXAMPLE\username</emphasis> with an AD server but to
|
|
|
- <emphasis>username@example.com</emphasis> with an OpenLDAP server, that may be awkward for the
|
|
|
|
|
- application's high-level logic).
|
|
|
|
|
|
|
+ <emphasis>username@example.com</emphasis> with an OpenLDAP server, that may
|
|
|
|
|
+ be awkward for the application's high-level logic).
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
The FQDN domain name for which the target LDAP server is an authority (e.g.,
|
|
The FQDN domain name for which the target LDAP server is an authority (e.g.,
|
|
|
- <filename>example.com</filename>). 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
|
|
|
|
|
- <emphasis>accountDomainName</emphasis> is <emphasis>foo.net</emphasis> and the
|
|
|
|
|
- user supplies <emphasis>bob@bar.net</emphasis>, 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., <emphasis>alice@foo.net</emphasis>) 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.
|
|
|
|
|
|
|
+ <filename>example.com</filename>). 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 <emphasis>accountDomainName</emphasis> is
|
|
|
|
|
+ <emphasis>foo.net</emphasis> and the user supplies
|
|
|
|
|
+ <emphasis>bob@bar.net</emphasis>, 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.,
|
|
|
|
|
+ <emphasis>alice@foo.net</emphasis>) 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.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
@@ -376,31 +415,36 @@ Array
|
|
|
<emphasis>FOO</emphasis>). Note that there is a 1:1 mapping between the
|
|
<emphasis>FOO</emphasis>). Note that there is a 1:1 mapping between the
|
|
|
<emphasis>accountDomainName</emphasis> and
|
|
<emphasis>accountDomainName</emphasis> and
|
|
|
<emphasis>accountDomainNameShort</emphasis>. This option should be used to
|
|
<emphasis>accountDomainNameShort</emphasis>. 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
|
|
|
|
|
- <emphasis>accountCanonicalForm</emphasis>). This option is not required but if it
|
|
|
|
|
- is not supplied, usernames in backslash form (e.g., <emphasis>FOO\alice</emphasis>) are not
|
|
|
|
|
- supported.
|
|
|
|
|
|
|
+ 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 <emphasis>accountCanonicalForm</emphasis>).
|
|
|
|
|
+ This option is not required but if it is not supplied, usernames in
|
|
|
|
|
+ backslash form (e.g., <emphasis>FOO\alice</emphasis>) are not supported.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountFilterFormat</emphasis></entry>
|
|
<entry><emphasis>accountFilterFormat</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The LDAP search filter used to search for accounts. This string is a
|
|
|
|
|
- <ulink url="http://php.net/printf"><methodname>printf()</methodname></ulink>-style expression that must
|
|
|
|
|
- contain one '<emphasis>%s</emphasis>' to accomodate the username. The default value is
|
|
|
|
|
|
|
+ The LDAP search filter used to search for accounts. This string is a <ulink
|
|
|
|
|
+ url="http://php.net/printf"><methodname>printf()</methodname></ulink>-style
|
|
|
|
|
+ expression that must contain one '<emphasis>%s</emphasis>' to accomodate the
|
|
|
|
|
+ username. The default value is
|
|
|
'<emphasis>(&(objectClass=user)(sAMAccountName=%s))</emphasis>', unless
|
|
'<emphasis>(&(objectClass=user)(sAMAccountName=%s))</emphasis>', unless
|
|
|
- <emphasis>bindRequiresDn</emphasis> is set to <constant>TRUE</constant>, in which case
|
|
|
|
|
- the default is '<emphasis>(&(objectClass=posixAccount)(uid=%s))</emphasis>'. For example, if for
|
|
|
|
|
- some reason you wanted to use <emphasis>bindRequiresDn = true</emphasis> with AD you would need to set
|
|
|
|
|
- <emphasis>accountFilterFormat = '(&(objectClass=user)(sAMAccountName=%s))</emphasis>'.
|
|
|
|
|
|
|
+ <emphasis>bindRequiresDn</emphasis> is set to <constant>TRUE</constant>, in
|
|
|
|
|
+ which case the default is
|
|
|
|
|
+ '<emphasis>(&(objectClass=posixAccount)(uid=%s))</emphasis>'. For
|
|
|
|
|
+ example, if for some reason you wanted to use
|
|
|
|
|
+ <emphasis>bindRequiresDn = true</emphasis> with AD you would need to set
|
|
|
|
|
+ <emphasis>accountFilterFormat =
|
|
|
|
|
+ '(&(objectClass=user)(sAMAccountName=%s))</emphasis>'.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>optReferrals</emphasis></entry>
|
|
<entry><emphasis>optReferrals</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- If set to <constant>TRUE</constant>, this option indicates to the LDAP client that referrals should
|
|
|
|
|
- be followed. The default value is <constant>FALSE</constant>.
|
|
|
|
|
|
|
+ If set to <constant>TRUE</constant>, this option indicates to the LDAP
|
|
|
|
|
+ client that referrals should be followed. The default value is
|
|
|
|
|
+ <constant>FALSE</constant>.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
</tbody>
|
|
</tbody>
|
|
@@ -410,14 +454,16 @@ Array
|
|
|
|
|
|
|
|
<note>
|
|
<note>
|
|
|
<para>
|
|
<para>
|
|
|
- If you enable <emphasis>useStartTls = true</emphasis> or <emphasis>useSsl = true</emphasis> 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
|
|
|
|
|
- "<emphasis>TLS_REQCERT never</emphasis>" in the OpenLDAP client <filename>ldap.conf</filename> (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.
|
|
|
|
|
|
|
+ If you enable <emphasis>useStartTls = true</emphasis> or
|
|
|
|
|
+ <emphasis>useSsl = true</emphasis> 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 "<emphasis>TLS_REQCERT never</emphasis>" in the OpenLDAP
|
|
|
|
|
+ client <filename>ldap.conf</filename> (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.
|
|
|
</para>
|
|
</para>
|
|
|
</note>
|
|
</note>
|
|
|
|
|
|
|
@@ -428,10 +474,10 @@ Array
|
|
|
<title>Collecting Debugging Messages</title>
|
|
<title>Collecting Debugging Messages</title>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- <classname>Zend_Auth_Adapter_Ldap</classname> collects debugging information within its <methodname>authenticate()</methodname>
|
|
|
|
|
- method. This information is stored in the <classname>Zend_Auth_Result</classname> object as messages. The array
|
|
|
|
|
- returned by <classname>Zend_Auth_Result::getMessages()</classname> is described as follows:
|
|
|
|
|
-
|
|
|
|
|
|
|
+ <classname>Zend_Auth_Adapter_Ldap</classname> collects debugging information within its
|
|
|
|
|
+ <methodname>authenticate()</methodname> method. This information is stored in the
|
|
|
|
|
+ <classname>Zend_Auth_Result</classname> object as messages. The array returned by
|
|
|
|
|
+ <classname>Zend_Auth_Result::getMessages()</classname> is described as follows
|
|
|
<table id="zend.auth.adapter.ldap.debugging.table">
|
|
<table id="zend.auth.adapter.ldap.debugging.table">
|
|
|
<title>Debugging Messages</title>
|
|
<title>Debugging Messages</title>
|
|
|
<tgroup cols="2">
|
|
<tgroup cols="2">
|
|
@@ -445,16 +491,17 @@ Array
|
|
|
<row>
|
|
<row>
|
|
|
<entry>Index 0</entry>
|
|
<entry>Index 0</entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- A generic, user-friendly message that is suitable for displaying to users (e.g., "Invalid
|
|
|
|
|
- credentials"). If the authentication is successful, this string is empty.
|
|
|
|
|
|
|
+ A generic, user-friendly message that is suitable for displaying to users
|
|
|
|
|
+ (e.g., "Invalid credentials"). If the authentication is successful, this
|
|
|
|
|
+ string is empty.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry>Index 1</entry>
|
|
<entry>Index 1</entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- A more detailed error message that is not suitable to be displayed to users but should be
|
|
|
|
|
- logged for the benefit of server operators. If the authentication is successful, this string is
|
|
|
|
|
- empty.
|
|
|
|
|
|
|
+ A more detailed error message that is not suitable to be displayed to users
|
|
|
|
|
+ but should be logged for the benefit of server operators. If the
|
|
|
|
|
+ authentication is successful, this string is empty.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
@@ -467,9 +514,10 @@ Array
|
|
|
</tgroup>
|
|
</tgroup>
|
|
|
</table>
|
|
</table>
|
|
|
|
|
|
|
|
- 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).
|
|
|
|
|
|
|
+ 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).
|
|
|
</para>
|
|
</para>
|
|
|
|
|
|
|
|
</sect2>
|
|
</sect2>
|
|
@@ -504,49 +552,52 @@ Array
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>useStartTls</emphasis></entry>
|
|
<entry><emphasis>useStartTls</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- For the sake of security, this should be <constant>TRUE</constant> if the server has the necessary
|
|
|
|
|
- certificate installed.
|
|
|
|
|
|
|
+ For the sake of security, this should be <constant>TRUE</constant> if
|
|
|
|
|
+ the server has the necessary certificate installed.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>useSsl</emphasis></entry>
|
|
<entry><emphasis>useSsl</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Possibly used as an alternative to <emphasis>useStartTls</emphasis> (see above).
|
|
|
|
|
|
|
+ Possibly used as an alternative to <emphasis>useStartTls</emphasis> (see
|
|
|
|
|
+ above).
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- As with all servers, this option is required. By default AD places all user accounts under
|
|
|
|
|
- the <emphasis>Users</emphasis> container (e.g.,
|
|
|
|
|
- <emphasis>CN=Users,DC=foo,DC=net</emphasis>), but the default is not common in larger
|
|
|
|
|
- organizations. Ask your AD administrator what the best DN for accounts for your application
|
|
|
|
|
- would be.
|
|
|
|
|
|
|
+ As with all servers, this option is required. By default AD places all
|
|
|
|
|
+ user accounts under the <emphasis>Users</emphasis> container (e.g.,
|
|
|
|
|
+ <emphasis>CN=Users,DC=foo,DC=net</emphasis>), but the default is not
|
|
|
|
|
+ common in larger organizations. Ask your AD administrator what the best
|
|
|
|
|
+ DN for accounts for your application would be.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
You almost certainly want this to be 3 for backslash style names (e.g.,
|
|
You almost certainly want this to be 3 for backslash style names (e.g.,
|
|
|
- <emphasis>FOO\alice</emphasis>), which are most familiar to Windows users. You should
|
|
|
|
|
- <emphasis>not</emphasis> use the unqualified form 2 (e.g., <emphasis>alice</emphasis>), as
|
|
|
|
|
- this may grant access to your application to users with the same username in other trusted
|
|
|
|
|
- domains (e.g., <emphasis>BAR\alice</emphasis> and <emphasis>FOO\alice</emphasis> will be
|
|
|
|
|
- treated as the same user). (See also note below.)
|
|
|
|
|
|
|
+ <emphasis>FOO\alice</emphasis>), which are most familiar to Windows
|
|
|
|
|
+ users. You should <emphasis>not</emphasis> use the unqualified form 2
|
|
|
|
|
+ (e.g., <emphasis>alice</emphasis>), as this may grant access to your
|
|
|
|
|
+ application to users with the same username in other trusted domains
|
|
|
|
|
+ (e.g., <emphasis>BAR\alice</emphasis> and <emphasis>FOO\alice</emphasis>
|
|
|
|
|
+ will be treated as the same user). (See also note below.)
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- This is required with AD unless <emphasis>accountCanonicalForm</emphasis> 2
|
|
|
|
|
- is used, which, again, is discouraged.
|
|
|
|
|
|
|
+ This is required with AD unless
|
|
|
|
|
+ <emphasis>accountCanonicalForm</emphasis> 2 is used, which, again, is
|
|
|
|
|
+ discouraged.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountDomainNameShort</emphasis></entry>
|
|
<entry><emphasis>accountDomainNameShort</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The NetBIOS name of the domain that users are in and for which the AD server is an authority.
|
|
|
|
|
- This is required if the backslash style
|
|
|
|
|
|
|
+ The NetBIOS name of the domain that users are in and for which the AD
|
|
|
|
|
+ server is an authority. This is required if the backslash style
|
|
|
<emphasis>accountCanonicalForm</emphasis> is used.
|
|
<emphasis>accountCanonicalForm</emphasis> is used.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
@@ -557,11 +608,12 @@ Array
|
|
|
|
|
|
|
|
<note>
|
|
<note>
|
|
|
<para>
|
|
<para>
|
|
|
- Technically there should be no danger of accidental cross-domain authentication with the current
|
|
|
|
|
- <classname>Zend_Auth_Adapter_Ldap</classname> implementation, since server domains are explicitly checked,
|
|
|
|
|
- but this may not be true of a future implementation that discovers the domain at runtime, or if an
|
|
|
|
|
- alternative adapter is used (e.g., Kerberos). In general, account name ambiguity is known to be the
|
|
|
|
|
- source of security issues, so always try to use qualified account names.
|
|
|
|
|
|
|
+ Technically there should be no danger of accidental cross-domain authentication
|
|
|
|
|
+ with the current <classname>Zend_Auth_Adapter_Ldap</classname> implementation,
|
|
|
|
|
+ since server domains are explicitly checked, but this may not be true of a
|
|
|
|
|
+ future implementation that discovers the domain at runtime, or if an alternative
|
|
|
|
|
+ adapter is used (e.g., Kerberos). In general, account name ambiguity is known to
|
|
|
|
|
+ be the source of security issues, so always try to use qualified account names.
|
|
|
</para>
|
|
</para>
|
|
|
</note>
|
|
</note>
|
|
|
|
|
|
|
@@ -572,8 +624,8 @@ Array
|
|
|
<title>Options for OpenLDAP</title>
|
|
<title>Options for OpenLDAP</title>
|
|
|
|
|
|
|
|
<para>
|
|
<para>
|
|
|
- For OpenLDAP or a generic LDAP server using a typical posixAccount style schema, the following options
|
|
|
|
|
- are noteworthy:
|
|
|
|
|
|
|
+ For OpenLDAP or a generic LDAP server using a typical posixAccount style schema, the
|
|
|
|
|
+ following options are noteworthy:
|
|
|
|
|
|
|
|
<table id="zend.auth.adapter.ldap.options-common-server-specific.openldap.table">
|
|
<table id="zend.auth.adapter.ldap.options-common-server-specific.openldap.table">
|
|
|
<title>Options for OpenLDAP</title>
|
|
<title>Options for OpenLDAP</title>
|
|
@@ -594,66 +646,68 @@ Array
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>useStartTls</emphasis></entry>
|
|
<entry><emphasis>useStartTls</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- For the sake of security, this should be <constant>TRUE</constant> if the server has the necessary
|
|
|
|
|
- certificate installed.
|
|
|
|
|
|
|
+ For the sake of security, this should be <constant>TRUE</constant> if
|
|
|
|
|
+ the server has the necessary certificate installed.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>useSsl</emphasis></entry>
|
|
<entry><emphasis>useSsl</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Possibly used as an alternative to <emphasis>useStartTls</emphasis> (see above).
|
|
|
|
|
|
|
+ Possibly used as an alternative to <emphasis>useStartTls</emphasis> (see
|
|
|
|
|
+ above).
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>username</emphasis></entry>
|
|
<entry><emphasis>username</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Required and must be a DN, as OpenLDAP requires that usernames be in DN form when
|
|
|
|
|
- performing a bind. Try to use an unprivileged account.
|
|
|
|
|
|
|
+ Required and must be a DN, as OpenLDAP requires that usernames be in DN
|
|
|
|
|
+ form when performing a bind. Try to use an unprivileged account.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>password</emphasis></entry>
|
|
<entry><emphasis>password</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- The password corresponding to the username above, but this may be omitted if the LDAP
|
|
|
|
|
- server permits an anonymous binding to query user accounts.
|
|
|
|
|
|
|
+ The password corresponding to the username above, but this may be
|
|
|
|
|
+ omitted if the LDAP server permits an anonymous binding to query user
|
|
|
|
|
+ accounts.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>bindRequiresDn</emphasis></entry>
|
|
<entry><emphasis>bindRequiresDn</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Required and must be <constant>TRUE</constant>, as OpenLDAP requires that usernames be in DN form
|
|
|
|
|
- when performing a bind.
|
|
|
|
|
|
|
+ Required and must be <constant>TRUE</constant>, as OpenLDAP requires
|
|
|
|
|
+ that usernames be in DN form when performing a bind.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
<entry><emphasis>baseDn</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- As with all servers, this option is required and indicates the DN under which all accounts
|
|
|
|
|
- being authenticated are located.
|
|
|
|
|
|
|
+ As with all servers, this option is required and indicates the DN under
|
|
|
|
|
+ which all accounts being authenticated are located.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
<entry><emphasis>accountCanonicalForm</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
Optional, but the default value is 4 (principal style names like
|
|
Optional, but the default value is 4 (principal style names like
|
|
|
- <emphasis>alice@foo.net</emphasis>), which may not be ideal if your users are used to
|
|
|
|
|
- backslash style names (e.g., <emphasis>FOO\alice</emphasis>). For backslash style names use
|
|
|
|
|
- value 3.
|
|
|
|
|
|
|
+ <emphasis>alice@foo.net</emphasis>), which may not be ideal if your
|
|
|
|
|
+ users are used to backslash style names (e.g.,
|
|
|
|
|
+ <emphasis>FOO\alice</emphasis>). For backslash style names use value 3.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
<entry><emphasis>accountDomainName</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
- Required unless you're using <emphasis>accountCanonicalForm</emphasis> 2,
|
|
|
|
|
- which is not recommended.
|
|
|
|
|
|
|
+ Required unless you're using <emphasis>accountCanonicalForm</emphasis>
|
|
|
|
|
+ 2, which is not recommended.
|
|
|
</entry>
|
|
</entry>
|
|
|
</row>
|
|
</row>
|
|
|
<row>
|
|
<row>
|
|
|
<entry><emphasis>accountDomainNameShort</emphasis></entry>
|
|
<entry><emphasis>accountDomainNameShort</emphasis></entry>
|
|
|
<entry>
|
|
<entry>
|
|
|
If AD is not also being used, this value is not required. Otherwise, if
|
|
If AD is not also being used, this value is not required. Otherwise, if
|
|
|
- <emphasis>accountCanonicalForm</emphasis> 3 is used, this option is required
|
|
|
|
|
- and should be a short name that corresponds adequately to the
|
|
|
|
|
|
|
+ <emphasis>accountCanonicalForm</emphasis> 3 is used, this option is
|
|
|
|
|
+ required and should be a short name that corresponds adequately to the
|
|
|
<emphasis>accountDomainName</emphasis> (e.g., if your
|
|
<emphasis>accountDomainName</emphasis> (e.g., if your
|
|
|
<emphasis>accountDomainName</emphasis> is
|
|
<emphasis>accountDomainName</emphasis> is
|
|
|
<emphasis>foo.net</emphasis>, a good
|
|
<emphasis>foo.net</emphasis>, a good
|
thomas