documentation/manual/en/module_specs/Zend_Ldap-API.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.ldap.api" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>API overview</title>
   5
   6     <sect2 id="zend.ldap.api.configuration">
   7         <title>Configuration / options</title>
   8
   9         <para>
  10             The <classname>Zend_Ldap</classname> component accepts an array of options either
  11             supplied to the constructor or through the <methodname>setOptions()</methodname>
  12             method. The permitted options are as follows:
  13         </para>
  14
  15         <table id="zend.ldap.api.configuration.table">
  16             <title>Zend_Ldap Options</title>
  17
  18             <tgroup cols="2">
  19                 <thead>
  20                     <row>
  21                         <entry>Name</entry>
  22                         <entry>Description</entry>
  23                     </row>
  24                 </thead>
  25
  26                 <tbody>
  27                     <row>
  28                         <entry><property>host</property></entry>
  29
  30                         <entry>
  31                             The default hostname of <acronym>LDAP</acronym> server if not
  32                             supplied to <methodname>connect()</methodname> (also may be used
  33                             when trying to canonicalize usernames in
  34                             <methodname>bind()</methodname>).
  35                         </entry>
  36                     </row>
  37
  38                     <row>
  39                         <entry><property>port</property></entry>
  40
  41                         <entry>
  42                             Default port of <acronym>LDAP</acronym> server if not supplied to
  43                             <methodname>connect()</methodname>.
  44                         </entry>
  45                     </row>
  46
  47                     <row>
  48                         <entry><property>useStartTls</property></entry>
  49
  50                         <entry>
  51                             Whether or not the <acronym>LDAP</acronym> client should use
  52                             <acronym>TLS</acronym> (aka <acronym>SSLv2</acronym>) encrypted
  53                             transport. A value of <constant>TRUE</constant> is strongly favored
  54                             in production environments to prevent passwords from be transmitted in
  55                             clear text. The default value is <constant>FALSE</constant>, as servers
  56                             frequently require that a certificate be installed separately after
  57                             installation. The <emphasis>useSsl</emphasis> and
  58                             <emphasis>useStartTls</emphasis> options are mutually exclusive.
  59                             The <emphasis>useStartTls</emphasis> option should be favored
  60                             over <emphasis>useSsl</emphasis> but not all servers support
  61                             this newer mechanism.
  62                         </entry>
  63                     </row>
  64
  65                     <row>
  66                         <entry><property>useSsl</property></entry>
  67
  68                         <entry>
  69                             Whether or not the <acronym>LDAP</acronym> client should use
  70                             <acronym>SSL</acronym> encrypted transport. The
  71                             <emphasis>useSsl</emphasis> and <emphasis>useStartTls</emphasis>
  72                             options are mutually exclusive.
  73                         </entry>
  74                     </row>
  75
  76                     <row>
  77                         <entry><property>username</property></entry>
  78
  79                         <entry>
  80                             The default credentials username. Some servers require that this
  81                             be in DN form. This must be given in DN form if the
  82                             <acronym>LDAP</acronym> server requires a DN to bind and binding
  83                             should be possible with simple usernames.
  84                         </entry>
  85                     </row>
  86
  87                     <row>
  88                         <entry><property>password</property></entry>
  89
  90                         <entry>
  91                             The default credentials password (used only with username
  92                             above).
  93                         </entry>
  94                     </row>
  95
  96                     <row>
  97                         <entry><property>bindRequiresDn</property></entry>
  98
  99                         <entry>
 100                             If <constant>TRUE</constant>, this instructs
 101                             <classname>Zend_Ldap</classname> to retrieve the DN for the
 102                             account used to bind if the username is not
 103                             already in DN form. The default value is <constant>FALSE</constant>.
 104                         </entry>
 105                     </row>
 106
 107                     <row>
 108                         <entry><property>baseDn</property></entry>
 109
 110                         <entry>
 111                             The default base DN used for searching (e.g., for accounts).
 112                             This option is required for most account related operations and should
 113                             indicate the DN under which accounts are located.
 114                         </entry>
 115                     </row>
 116
 117                     <row>
 118                         <entry><property>accountCanonicalForm</property></entry>
 119
 120                         <entry>
 121                             A small integer indicating the form to which account names
 122                             should be canonicalized. See the <link
 123                                 linkend="zend.ldap.introduction.theory-of-operations.account-name-canonicalization"><emphasis>Account
 124                                 Name Canonicalization</emphasis></link>
 125                             section below.
 126                         </entry>
 127                     </row>
 128
 129                     <row>
 130                         <entry><property>accountDomainName</property></entry>
 131
 132                         <entry>
 133                             The <acronym>FQDN</acronym> domain for which the target
 134                             <acronym>LDAP</acronym> server is an authority (e.g., example.com).
 135                         </entry>
 136                     </row>
 137
 138                     <row>
 139                         <entry><property>accountDomainNameShort</property></entry>
 140
 141                         <entry>
 142                             The 'short' domain for which the target <acronym>LDAP</acronym> server
 143                             is an authority. This is usually used to specify the NetBIOS
 144                             domain name for Windows networks but may also be used by non-AD servers.
 145                         </entry>
 146                     </row>
 147
 148                     <row>
 149                         <entry><property>accountFilterFormat</property></entry>
 150
 151                         <entry>
 152                             The <acronym>LDAP</acronym> search filter used to search for accounts.
 153                             This string is a <ulink
 154                                 url="http://php.net/sprintf"><methodname>sprintf()</methodname></ulink>
 155                             style expression that must contain one '<emphasis>%s</emphasis>' to
 156                             accommodate the username. The default value is
 157                             '<emphasis>(&amp;(objectClass=user)(sAMAccountName=%s))</emphasis>'
 158                             unless <emphasis>bindRequiresDn</emphasis> is set to
 159                             <constant>TRUE</constant>, in which case the default is
 160                             '<emphasis>(&amp;(objectClass=posixAccount)(uid=%s))</emphasis>'.
 161                             Users of custom schemas may need to change this option.
 162                         </entry>
 163                     </row>
 164
 165                     <row>
 166                         <entry><property>allowEmptyPassword</property></entry>
 167
 168                         <entry>
 169                             Some <acronym>LDAP</acronym> servers can be configured to accept an
 170                             empty string password as an anonymous bind. This behavior is almost
 171                             always undesirable. For this reason, empty passwords are explicitly
 172                             disallowed. Set this value to <constant>TRUE</constant> to allow an
 173                             empty string password to be submitted during the bind.
 174                         </entry>
 175                     </row>
 176
 177                     <row>
 178                         <entry><property>optReferrals</property></entry>
 179
 180                         <entry>
 181                             If set to <constant>TRUE</constant>, this option indicates to the
 182                             <acronym>LDAP</acronym> client that referrals should be followed.
 183                             The default value is <constant>FALSE</constant>.
 184                         </entry>
 185                     </row>
 186
 187                     <row>
 188                         <entry><property>tryUsernameSplit</property></entry>
 189
 190                         <entry>
 191                             If set to <constant>FALSE</constant>, this option indicates that the
 192                             given username should not be split at the first <emphasis>@</emphasis>
 193                             or <emphasis>\</emphasis> character to separate the username from
 194                             the domain during the binding-procedure. This allows the user to
 195                             use usernames that contain an <emphasis>@</emphasis> or
 196                             <emphasis>\</emphasis> character that do not
 197                             inherit some domain-information, e.g. using email-addresses for
 198                             binding. The default value is <constant>TRUE</constant>.
 199                         </entry>
 200                     </row>
 201                 </tbody>
 202             </tgroup>
 203         </table>
 204     </sect2>
 205
 206     <sect2 id="zend.ldap.api.reference">
 207         <title>API Reference</title>
 208
 209         <note>
 210             <para>Method names in <emphasis>italics</emphasis> are static methods.</para>
 211         </note>
 212
 213         <xi:include href="Zend_Ldap-API-Ldap.xml" />
 214         <xi:include href="Zend_Ldap-API-Ldap-Attribute.xml" />
 215         <xi:include href="Zend_Ldap-API-Ldap-Dn.xml" />
 216         <xi:include href="Zend_Ldap-API-Ldap-Filter.xml" />
 217         <xi:include href="Zend_Ldap-API-Ldap-Node.xml" />
 218         <xi:include href="Zend_Ldap-API-Ldap-Node-RootDse.xml" />
 219         <xi:include href="Zend_Ldap-API-Ldap-Node-Schema.xml" />
 220         <xi:include href="Zend_Ldap-API-Ldap-Ldif-Encoder.xml" />
 221     </sect2>
 222 </sect1>