rubbos/app/apache2/manual/mod/mod_auth_ldap.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_auth_ldap - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.0</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_auth_ldap</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_auth_ldap.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Allows an LDAP directory to be used to store the database
  27 for HTTP Basic authentication.</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>auth_ldap_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_auth_ldap.c</td></tr>
  31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.41 and later</td></tr></table>
  32 <h3>Summary</h3>
  33
  34     <p><code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> supports the following features:</p>
  35
  36     <ul>
  37       <li>Known to support the <a href="http://www.openldap.org/">OpenLDAP SDK</a> (both 1.x
  38       and 2.x), <a href="http://developer.novell.com/ndk/cldap.htm">
  39       Novell LDAP SDK</a> and the <a href="http://www.iplanet.com/downloads/developer/">iPlanet
  40       (Netscape)</a> SDK.</li>
  41
  42       <li>Complex authorization policies can be implemented by
  43       representing the policy with LDAP filters.</li>
  44
  45       <li>Support for Microsoft FrontPage allows FrontPage users to
  46       control access to their webs, while retaining LDAP for user
  47       authentication.</li>
  48
  49       <li>Uses extensive caching of LDAP operations via <a href="mod_ldap.html">mod_ldap</a>.</li>
  50
  51       <li>Support for LDAP over SSL (requires the Netscape SDK) or
  52       TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).</li>
  53     </ul>
  54 </div>
  55 <div id="quickview"><h3 class="directives">Directives</h3>
  56 <ul id="toc">
  57 <li><img alt="" src="../images/down.gif" /> <a href="#authldapauthoritative">AuthLDAPAuthoritative</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#authldapbinddn">AuthLDAPBindDN</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#authldapbindpassword">AuthLDAPBindPassword</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#authldapcharsetconfig">AuthLDAPCharsetConfig</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#authldapdereferencealiases">AuthLDAPDereferenceAliases</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#authldapenabled">AuthLDAPEnabled</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#authldapfrontpagehack">AuthLDAPFrontPageHack</a></li>
  65 <li><img alt="" src="../images/down.gif" /> <a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#authldapremoteuserisdn">AuthLDAPRemoteUserIsDN</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#authldapurl">AuthLDAPUrl</a></li>
  69 </ul>
  70 <h3>Topics</h3>
  71 <ul id="topics">
  72 <li><img alt="" src="../images/down.gif" /> <a href="#contents">Contents</a></li>
  73 <li><img alt="" src="../images/down.gif" /> <a href="#operation">Operation</a></li>
  74 <li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#usingtls">Using TLS</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#usingssl">Using SSL</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#frontpage">Using Microsoft
  79     FrontPage with mod_auth_ldap</a></li>
  80 </ul><h3>See also</h3>
  81 <ul class="seealso">
  82 <li><code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code></li>
  83 </ul></div>
  84 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  85 <div class="section">
  86 <h2><a name="contents" id="contents">Contents</a></h2>
  87
  88     <ul>
  89       <li>
  90         <a href="#operation">Operation</a>
  91
  92         <ul>
  93           <li><a href="#authenphase">The Authentication
  94           Phase</a></li>
  95
  96           <li><a href="#authorphase">The Authorization
  97           Phase</a></li>
  98         </ul>
  99       </li>
 100
 101       <li>
 102         <a href="#requiredirectives">The Require Directives</a>
 103
 104         <ul>
 105           <li><a href="#reqvaliduser">Require valid-user</a></li>
 106           <li><a href="#requser">Require user</a></li>
 107           <li><a href="#reqgroup">Require group</a></li>
 108           <li><a href="#reqdn">Require dn</a></li>
 109           <li><a href="#reqattribute">Require ldap-attribute</a></li>
 110         </ul>
 111       </li>
 112
 113       <li><a href="#examples">Examples</a></li>
 114       <li><a href="#usingtls">Using TLS</a></li>
 115       <li><a href="#usingssl">Using SSL</a></li>
 116
 117       <li>
 118         <a href="#frontpage">Using Microsoft FrontPage with
 119         <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code></a>
 120
 121         <ul>
 122           <li><a href="#howitworks">How It Works</a></li>
 123           <li><a href="#fpcaveats">Caveats</a></li>
 124         </ul>
 125       </li>
 126     </ul>
 127 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 128 <div class="section">
 129 <h2><a name="operation" id="operation">Operation</a></h2>
 130
 131     <p>There are two phases in granting access to a user. The first
 132     phase is authentication, in which <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code>
 133     verifies that the user's credentials are valid. This also called
 134     the <em>search/bind</em> phase. The second phase is
 135     authorization, in which <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> determines
 136     if the authenticated user is allowed access to the resource in
 137     question. This is also known as the <em>compare</em>
 138     phase.</p>
 139
 140 <h3><a name="authenphase" id="authenphase">The Authentication
 141     Phase</a></h3>
 142
 143     <p>During the authentication phase, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code>
 144     searches for an entry in the directory that matches the username
 145     that the HTTP client passes. If a single unique match is found,
 146     then <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> attempts to bind to the
 147     directory server using the DN of the entry plus the password
 148     provided by the HTTP client. Because it does a search, then a
 149     bind, it is often referred to as the search/bind phase. Here are
 150     the steps taken during the search/bind phase.</p>
 151
 152     <ol>
 153       <li>Generate a search filter by combining the attribute and
 154       filter provided in the <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> directive with
 155       the username passed by the HTTP client.</li>
 156
 157       <li>Search the directory using the generated filter. If the
 158       search does not return exactly one entry, deny or decline
 159       access.</li>
 160
 161       <li>Fetch the distinguished name of the entry retrieved from
 162       the search and attempt to bind to the LDAP server using the
 163       DN and the password passed by the HTTP client. If the bind is
 164       unsuccessful, deny or decline access.</li>
 165     </ol>
 166
 167     <p>The following directives are used during the search/bind
 168     phase</p>
 169
 170     <table>
 171
 172       <tr>
 173         <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code></td>
 174
 175         <td>Specifies the LDAP server, the
 176         base DN, the attribute to use in the search, as well as the
 177         extra search filter to use.</td>
 178       </tr>
 179
 180       <tr>
 181         <td><code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code></td>
 182
 183         <td>An optional DN to bind with
 184         during the search phase.</td>
 185       </tr>
 186
 187       <tr>
 188         <td><code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code></td>
 189
 190         <td>An optional password to bind
 191         with during the search phase.</td>
 192       </tr>
 193     </table>
 194
 195
 196 <h3><a name="authorphase" id="authorphase">The Authorization
 197     Phase</a></h3>
 198
 199     <p>During the authorization phase, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code>
 200     attempts to determine if the user is authorized to access the
 201     resource.  Many of these checks require
 202     <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> to do a compare operation on the
 203     LDAP server. This is why this phase is often referred to as the
 204     compare phase. <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> accepts the
 205     following <code class="directive"><a href="../mod/core.html#require">Require</a></code>
 206     directives to determine if the credentials are acceptable:</p>
 207
 208     <ul>
 209       <li>Grant access if there is a <a href="#requser"><code>Require
 210       valid-user</code></a> directive.</li>
 211
 212       <li>Grant access if there is a <a href="#reqgroup"><code>Require user</code></a> directive, and the
 213       username in the directive matches the username passed by the
 214       client.</li>
 215
 216       <li>Grant access if there is a <a href="#reqdn"><code>Require
 217       dn</code></a> directive, and the DN in the directive matches
 218       the DN fetched from the LDAP directory.</li>
 219
 220       <li>Grant access if there is a <a href="#reqgroup"><code>Require group</code></a> directive, and
 221       the DN fetched from the LDAP directory (or the username
 222       passed by the client) occurs in the LDAP group.</li>
 223
 224       <li>Grant access if there is a <a href="#reqattribute">
 225       <code>Require ldap-attribute</code></a>
 226       directive, and the attribute fetched from the LDAP directory
 227       matches the given value.</li>
 228
 229       <li>otherwise, deny or decline access</li>
 230     </ul>
 231
 232     <p><code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> uses the following directives during the
 233     compare phase:</p>
 234
 235     <table>
 236
 237       <tr>
 238         <td><code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> </td>
 239
 240         <td>The attribute specified in the
 241         URL is used in compare operations for the <code>Require
 242         user</code> operation.</td>
 243       </tr>
 244
 245       <tr>
 246         <td><code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code></td>
 247
 248         <td>Determines the behavior of the
 249         <code>Require dn</code> directive.</td>
 250       </tr>
 251
 252       <tr>
 253         <td><code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code></td>
 254
 255         <td>Determines the attribute to
 256         use for comparisons in the <code>Require group</code>
 257         directive.</td>
 258       </tr>
 259
 260       <tr>
 261         <td><code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code></td>
 262
 263         <td>Specifies whether to use the
 264         user DN or the username when doing comparisons for the
 265         <code>Require group</code> directive.</td>
 266       </tr>
 267     </table>
 268
 269 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 270 <div class="section">
 271 <h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
 272
 273     <p>Apache's <code class="directive"><a href="../mod/core.html#require">Require</a></code>
 274     directives are used during the authorization phase to ensure that
 275     a user is allowed to access a resource.</p>
 276
 277 <h3><a name="reqvaliduser" id="reqvaliduser">Require
 278     valid-user</a></h3>
 279
 280     <p>If this directive exists, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> grants
 281     access to any user that has successfully authenticated during the
 282     search/bind phase.</p>
 283
 284
 285 <h3><a name="requser" id="requser">Require user</a></h3>
 286
 287     <p>The <code>Require user</code> directive specifies what
 288     usernames can access the resource. Once
 289     <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> has retrieved a unique DN from the
 290     directory, it does an LDAP compare operation using the username
 291     specified in the <code>Require user</code> to see if that username
 292     is part of the just-fetched LDAP entry.  Multiple users can be
 293     granted access by putting multiple usernames on the line,
 294     separated with spaces. If a username has a space in it, then it
 295     must be surrounded with double quotes. Multiple users can also be
 296     granted access by using multiple <code>Require user</code>
 297     directives, with one user per line. For example, with a <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> of
 298     <code>ldap://ldap/o=Airius?cn</code> (i.e., <code>cn</code> is
 299     used for searches), the following Require directives could be used
 300     to restrict access:</p>
 301 <div class="example"><p><code>
 302 Require user "Barbara Jenson"<br />
 303 Require user "Fred User"<br />
 304 Require user "Joe Manager"<br />
 305 </code></p></div>
 306
 307     <p>Because of the way that <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> handles this
 308     directive, Barbara Jenson could sign on as <em>Barbara
 309     Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
 310     she has in her LDAP entry. Only the single <code>Require
 311     user</code> line is needed to support all values of the attribute
 312     in the user's entry.</p>
 313
 314     <p>If the <code>uid</code> attribute was used instead of the
 315     <code>cn</code> attribute in the URL above, the above three lines
 316     could be condensed to</p>
 317 <div class="example"><p><code>Require user bjenson fuser jmanager</code></p></div>
 318
 319
 320 <h3><a name="reqgroup" id="reqgroup">Require group</a></h3>
 321
 322     <p>This directive specifies an LDAP group whose members are
 323     allowed access. It takes the distinguished name of the LDAP
 324     group. Note: Do not surround the group name with quotes.
 325     For example, assume that the following entry existed in
 326     the LDAP directory:</p>
 327 <div class="example"><p><code>
 328 dn: cn=Administrators, o=Airius<br />
 329 objectClass: groupOfUniqueNames<br />
 330 uniqueMember: cn=Barbara Jenson, o=Airius<br />
 331 uniqueMember: cn=Fred User, o=Airius<br />
 332 </code></p></div>
 333
 334     <p>The following directive would grant access to both Fred and
 335     Barbara:</p>
 336 <div class="example"><p><code>Require group cn=Administrators, o=Airius</code></p></div>
 337
 338     <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapgroupattribute">AuthLDAPGroupAttribute</a></code> and
 339     <code class="directive"><a href="#authldapgroupattributeisdn">AuthLDAPGroupAttributeIsDN</a></code>
 340     directives.</p>
 341
 342
 343 <h3><a name="reqdn" id="reqdn">Require dn</a></h3>
 344
 345     <p>The <code>Require dn</code> directive allows the administrator
 346     to grant access based on distinguished names. It specifies a DN
 347     that must match for access to be granted. If the distinguished
 348     name that was retrieved from the directory server matches the
 349     distinguished name in the <code>Require dn</code>, then
 350     authorization is granted. Note: do not surround the distinguished
 351     name with quotes.</p>
 352
 353     <p>The following directive would grant access to a specific
 354     DN:</p>
 355 <div class="example"><p><code>Require dn cn=Barbara Jenson, o=Airius</code></p></div>
 356
 357     <p>Behavior of this directive is modified by the <code class="directive"><a href="#authldapcomparednonserver">AuthLDAPCompareDNOnServer</a></code>
 358     directive.</p>
 359
 360
 361 <h3><a name="reqattribute" id="reqattribute">Require ldap-attribute</a></h3>
 362
 363     <p>The <code>Require ldap-attribute</code> directive allows the
 364     administrator to grant access based on attributes of the authenticated
 365     user in the LDAP directory.  If the attribute in the directory
 366     matches the value given in the configuration, access is granted.</p>
 367
 368     <p>The following directive would grant access to anyone with
 369     the attribute employeeType = active</p>
 370
 371     <div class="example"><p><code>Require ldap-attribute employeeType=active</code></p></div>
 372
 373     <p>Multiple attribute/value pairs can be specified on the same line
 374     separated by spaces or they can be specified in multiple
 375     <code>Require ldap-attribute</code> directives. The effect of listing
 376     multiple attribute/values pairs is an OR operation. Access will be
 377     granted if any of the listed attribute values match the value of a
 378     corresponding attribute in the user object. If the value of the
 379     attribute contains a space, only the value must be within double quotes.</p>
 380
 381     <p>The following directive would grant access to anyone with
 382     the city attribute equal to "San Jose" or status equal to "Active"</p>
 383
 384     <div class="example"><p><code>Require ldap-attribute city="San Jose" status=active</code></p></div>
 385
 386
 387 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 388 <div class="section">
 389 <h2><a name="examples" id="examples">Examples</a></h2>
 390
 391     <ul>
 392       <li>
 393         Grant access to anyone who exists in the LDAP directory,
 394         using their UID for searches.
 395
 396 <div class="example"><p><code>
 397  AuthLDAPURL "ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)"<br />
 398  Require valid-user
 399 </code></p></div>
 400       </li>
 401
 402       <li>
 403         The next example is the same as above; but with the fields
 404         that have useful defaults omitted. Also, note the use of a
 405         redundant LDAP server.
 406 <div class="example"><p><code>AuthLDAPURL "ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius"<br />
 407 Require valid-user
 408 </code></p></div>
 409       </li>
 410
 411       <li>
 412         The next example is similar to the previous one, but is
 413         uses the common name instead of the UID. Note that this
 414         could be problematical if multiple people in the directory
 415         share the same <code>cn</code>, because a search on <code>cn</code>
 416         <strong>must</strong> return exactly one entry. That's why
 417         this approach is not recommended: it's a better idea to
 418         choose an attribute that is guaranteed unique in your
 419         directory, such as <code>uid</code>.
 420 <div class="example"><p><code>
 421 AuthLDAPURL "ldap://ldap.airius.com/ou=People, o=Airius?cn"<br />
 422 Require valid-user
 423 </code></p></div>
 424       </li>
 425
 426       <li>
 427         Grant access to anybody in the Administrators group. The
 428         users must authenticate using their UID.
 429 <div class="example"><p><code>
 430 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid<br />
 431 Require group cn=Administrators, o=Airius
 432 </code></p></div>
 433       </li>
 434
 435       <li>
 436         The next example assumes that everyone at Airius who
 437         carries an alphanumeric pager will have an LDAP attribute
 438         of <code>qpagePagerID</code>. The example will grant access
 439         only to people (authenticated via their UID) who have
 440         alphanumeric pagers:
 441 <div class="example"><p><code>
 442 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)<br />
 443 Require valid-user
 444 </code></p></div>
 445       </li>
 446
 447       <li>
 448         <p>The next example demonstrates the power of using filters
 449         to accomplish complicated administrative requirements.
 450         Without filters, it would have been necessary to create a
 451         new LDAP group and ensure that the group's members remain
 452         synchronized with the pager users. This becomes trivial
 453         with filters. The goal is to grant access to anyone who has
 454         a filter, plus grant access to Joe Manager, who doesn't
 455         have a pager, but does need to access the same
 456         resource:</p>
 457 <div class="example"><p><code>
 458 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))<br />
 459 Require valid-user
 460 </code></p></div>
 461
 462         <p>This last may look confusing at first, so it helps to
 463         evaluate what the search filter will look like based on who
 464         connects, as shown below. The text in blue is the part that
 465         is filled in using the attribute specified in the URL. The
 466         text in red is the part that is filled in using the filter
 467         specified in the URL. The text in green is filled in using
 468         the information that is retrieved from the HTTP client. If
 469         Fred User connects as <code>fuser</code>, the filter would look
 470         like</p>
 471
 472         <div class="example"><p><code>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</code></p></div>
 473
 474         <p>The above search will only succeed if <em>fuser</em> has a
 475         pager. When Joe Manager connects as <em>jmanager</em>, the
 476         filter looks like</p>
 477
 478         <div class="example"><p><code>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</code></p></div>
 479
 480         <p>The above search will succeed whether <em>jmanager</em>
 481         has a pager or not.</p>
 482       </li>
 483     </ul>
 484 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 485 <div class="section">
 486 <h2><a name="usingtls" id="usingtls">Using TLS</a></h2>
 487
 488     <p>To use TLS, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedca">LDAPTrustedCA</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedcatype">LDAPTrustedCAType</a></code>.</p>
 489 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 490 <div class="section">
 491 <h2><a name="usingssl" id="usingssl">Using SSL</a></h2>
 492
 493     <p>To use SSL, see the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> directives <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedca">LDAPTrustedCA</a></code> and <code class="directive"><a href="../mod/mod_ldap.html#ldaptrustedcatype">LDAPTrustedCAType</a></code>.</p>
 494
 495     <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
 496     <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code>
 497     directive, instead of <em>ldap://</em>.</p>
 498 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 499 <div class="section">
 500 <h2><a name="frontpage" id="frontpage">Using Microsoft
 501     FrontPage with mod_auth_ldap</a></h2>
 502
 503     <p>Normally, FrontPage uses FrontPage-web-specific user/group
 504     files (i.e., the <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code> module) to handle all
 505     authentication. Unfortunately, it is not possible to just
 506     change to LDAP authentication by adding the proper directives,
 507     because it will break the <em>Permissions</em> forms in
 508     the FrontPage client, which attempt to modify the standard
 509     text-based authorization files.</p>
 510
 511     <p>Once a FrontPage web has been created, adding LDAP
 512     authentication to it is a matter of adding the following
 513     directives to <em>every</em> <code>.htaccess</code> file
 514     that gets created in the web</p>
 515 <div class="example"><pre>
 516 AuthLDAPURL            "the url"
 517 AuthLDAPAuthoritative  off
 518 AuthLDAPFrontPageHack  on
 519 </pre></div>
 520
 521     <p><code class="directive"><a href="#authldapauthoritative">AuthLDAPAuthoritative</a></code> must be
 522     off to allow <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> to decline group
 523     authentication so that Apache will fall back to file
 524     authentication for checking group membership. This allows the
 525     FrontPage-managed group file to be used.</p>
 526
 527 <h3><a name="howitworks" id="howitworks">How It Works</a></h3>
 528
 529     <p>FrontPage restricts access to a web by adding the <code>Require
 530     valid-user</code> directive to the <code>.htaccess</code>
 531     files. If <code class="directive"><a href="#authldapfrontpagehack">AuthLDAPFrontPageHack</a></code> is not
 532     on, the <code>Require valid-user</code> directive will succeed for
 533     any user who is valid <em>as far as LDAP is
 534     concerned</em>. This means that anybody who has an entry in
 535     the LDAP directory is considered a valid user, whereas FrontPage
 536     considers only those people in the local user file to be
 537     valid. The purpose of the hack is to force Apache to consult the
 538     local user file (which is managed by FrontPage) - instead of LDAP
 539     - when handling the <code>Require valid-user</code> directive.</p>
 540
 541     <p>Once directives have been added as specified above,
 542     FrontPage users will be able to perform all management
 543     operations from the FrontPage client.</p>
 544
 545
 546 <h3><a name="fpcaveats" id="fpcaveats">Caveats</a></h3>
 547
 548     <ul>
 549       <li>When choosing the LDAP URL, the attribute to use for
 550       authentication should be something that will also be valid
 551       for putting into a <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code> user file.
 552       The user ID is ideal for this.</li>
 553
 554       <li>When adding users via FrontPage, FrontPage administrators
 555       should choose usernames that already exist in the LDAP
 556       directory (for obvious reasons). Also, the password that the
 557       administrator enters into the form is ignored, since Apache
 558       will actually be authenticating against the password in the
 559       LDAP database, and not against the password in the local user
 560       file. This could cause confusion for web administrators.</li>
 561
 562
 563       <li>Apache must be compiled with <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code> in order to
 564       use FrontPage support. This is because Apache will still use
 565       the <code class="module"><a href="../mod/mod_auth.html">mod_auth</a></code> group file for determine the extent of a
 566       user's access to the FrontPage web.</li>
 567
 568       <li>The directives must be put in the <code>.htaccess</code>
 569       files. Attempting to put them inside <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> or <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> directives won't work. This
 570       is because <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> has to be able to grab
 571       the <code class="directive"><a href="../mod/mod_auth.html#authuserfile">AuthUserFile</a></code>
 572       directive that is found in FrontPage <code>.htaccess</code>
 573       files so that it knows where to look for the valid user list. If
 574       the <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> directives aren't in the same
 575       <code>.htaccess</code> file as the FrontPage directives, then
 576       the hack won't work, because <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will
 577       never get a chance to process the <code>.htaccess</code> file,
 578       and won't be able to find the FrontPage-managed user file.</li>
 579     </ul>
 580
 581 </div>
 582 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 583 <div class="directive-section"><h2><a name="AuthLDAPAuthoritative" id="AuthLDAPAuthoritative">AuthLDAPAuthoritative</a> <a name="authldapauthoritative" id="authldapauthoritative">Directive</a></h2>
 584 <table class="directive">
 585 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Prevent other authentication modules from
 586 authenticating the user if this one fails</td></tr>
 587 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPAuthoritative on|off</code></td></tr>
 588 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPAuthoritative on</code></td></tr>
 589 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 590 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 591 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 592 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 593 </table>
 594     <p>Set to <code>off</code> if this module should let other
 595     authentication modules attempt to authenticate the user, should
 596     authentication with this module fail. Control is only passed on
 597     to lower modules if there is no DN or rule that matches the
 598     supplied user name (as passed by the client).</p>
 599
 600 </div>
 601 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 602 <div class="directive-section"><h2><a name="AuthLDAPBindDN" id="AuthLDAPBindDN">AuthLDAPBindDN</a> <a name="authldapbinddn" id="authldapbinddn">Directive</a></h2>
 603 <table class="directive">
 604 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Optional DN to use in binding to the LDAP server</td></tr>
 605 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindDN <em>distinguished-name</em></code></td></tr>
 606 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 607 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 608 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 609 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 610 </table>
 611     <p>An optional DN used to bind to the server when searching for
 612     entries. If not provided, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will use
 613     an anonymous bind.</p>
 614
 615 </div>
 616 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 617 <div class="directive-section"><h2><a name="AuthLDAPBindPassword" id="AuthLDAPBindPassword">AuthLDAPBindPassword</a> <a name="authldapbindpassword" id="authldapbindpassword">Directive</a></h2>
 618 <table class="directive">
 619 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Password used in conjuction with the bind DN</td></tr>
 620 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPBindPassword <em>password</em></code></td></tr>
 621 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 622 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 623 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 624 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 625 </table>
 626     <p>A bind password to use in conjunction with the bind DN. Note
 627     that the bind password is probably sensitive data, and should be
 628     properly protected. You should only use the <code class="directive"><a href="#authldapbinddn">AuthLDAPBindDN</a></code> and <code class="directive"><a href="#authldapbindpassword">AuthLDAPBindPassword</a></code> if you
 629     absolutely need them to search the directory.</p>
 630
 631 </div>
 632 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 633 <div class="directive-section"><h2><a name="AuthLDAPCharsetConfig" id="AuthLDAPCharsetConfig">AuthLDAPCharsetConfig</a> <a name="authldapcharsetconfig" id="authldapcharsetconfig">Directive</a></h2>
 634 <table class="directive">
 635 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Language to charset conversion configuration file</td></tr>
 636 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCharsetConfig <em>file-path</em></code></td></tr>
 637 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 638 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 639 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 640 </table>
 641     <p>The <code class="directive">AuthLDAPCharsetConfig</code> directive sets the location
 642     of the language to charset conversion configuration file. <var>File-path</var> is relative
 643     to the <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. This file specifies
 644     the list of language extensions to character sets.
 645     Most administrators use the provided <code>charset.conv</code>
 646     file, which associates common language extensions to character sets.</p>
 647
 648     <p>The file contains lines in the following format:</p>
 649
 650     <div class="example"><p><code>
 651       <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
 652     </code></p></div>
 653
 654     <p>The case of the extension does not matter. Blank lines, and lines
 655     beginning with a hash character (<code>#</code>) are ignored.</p>
 656
 657 </div>
 658 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 659 <div class="directive-section"><h2><a name="AuthLDAPCompareDNOnServer" id="AuthLDAPCompareDNOnServer">AuthLDAPCompareDNOnServer</a> <a name="authldapcomparednonserver" id="authldapcomparednonserver">Directive</a></h2>
 660 <table class="directive">
 661 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the LDAP server to compare the DNs</td></tr>
 662 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPCompareDNOnServer on|off</code></td></tr>
 663 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPCompareDNOnServer on</code></td></tr>
 664 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 665 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 666 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 667 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 668 </table>
 669     <p>When set, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will use the LDAP
 670     server to compare the DNs. This is the only foolproof way to
 671     compare DNs.  <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will search the
 672     directory for the DN specified with the <a href="#reqdn"><code>Require dn</code></a> directive, then,
 673     retrieve the DN and compare it with the DN retrieved from the user
 674     entry. If this directive is not set,
 675     <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> simply does a string comparison. It
 676     is possible to get false negatives with this approach, but it is
 677     much faster. Note the <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code> cache can speed up
 678     DN comparison in most situations.</p>
 679
 680 </div>
 681 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 682 <div class="directive-section"><h2><a name="AuthLDAPDereferenceAliases" id="AuthLDAPDereferenceAliases">AuthLDAPDereferenceAliases</a> <a name="authldapdereferencealiases" id="authldapdereferencealiases">Directive</a></h2>
 683 <table class="directive">
 684 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>When will the module de-reference aliases</td></tr>
 685 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPDereferenceAliases never|searching|finding|always</code></td></tr>
 686 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPDereferenceAliases Always</code></td></tr>
 687 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 688 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 689 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 690 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 691 </table>
 692     <p>This directive specifies when <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will
 693     de-reference aliases during LDAP operations. The default is
 694     <code>always</code>.</p>
 695
 696 </div>
 697 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 698 <div class="directive-section"><h2><a name="AuthLDAPEnabled" id="AuthLDAPEnabled">AuthLDAPEnabled</a> <a name="authldapenabled" id="authldapenabled">Directive</a></h2>
 699 <table class="directive">
 700 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Turn on or off LDAP authentication</td></tr>
 701 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> AuthLDAPEnabled on|off</code></td></tr>
 702 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPEnabled on</code></td></tr>
 703 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 704 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 705 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 706 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 707 </table>
 708     <p>Set to <code>off</code> to disable
 709     <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> in certain directories. This is
 710     useful if you have <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> enabled at or
 711     near the top of your tree, but want to disable it completely in
 712     certain locations.</p>
 713
 714 </div>
 715 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 716 <div class="directive-section"><h2><a name="AuthLDAPFrontPageHack" id="AuthLDAPFrontPageHack">AuthLDAPFrontPageHack</a> <a name="authldapfrontpagehack" id="authldapfrontpagehack">Directive</a></h2>
 717 <table class="directive">
 718 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow LDAP authentication to work with MS FrontPage</td></tr>
 719 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPFrontPageHack on|off</code></td></tr>
 720 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPFrontPageHack off</code></td></tr>
 721 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 722 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 723 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 724 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 725 </table>
 726     <p>See the section on <a href="#frontpage">using Microsoft
 727     FrontPage</a> with <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code>.</p>
 728
 729 </div>
 730 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 731 <div class="directive-section"><h2><a name="AuthLDAPGroupAttribute" id="AuthLDAPGroupAttribute">AuthLDAPGroupAttribute</a> <a name="authldapgroupattribute" id="authldapgroupattribute">Directive</a></h2>
 732 <table class="directive">
 733 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>LDAP attributes used to check for group membership</td></tr>
 734 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttribute <em>attribute</em></code></td></tr>
 735 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 736 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 737 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 738 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 739 </table>
 740     <p>This directive specifies which LDAP attributes are used to
 741     check for group membership. Multiple attributes can be used by
 742     specifying this directive multiple times. If not specified,
 743     then <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> uses the <code>member</code> and
 744     <code>uniquemember</code> attributes.</p>
 745
 746 </div>
 747 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 748 <div class="directive-section"><h2><a name="AuthLDAPGroupAttributeIsDN" id="AuthLDAPGroupAttributeIsDN">AuthLDAPGroupAttributeIsDN</a> <a name="authldapgroupattributeisdn" id="authldapgroupattributeisdn">Directive</a></h2>
 749 <table class="directive">
 750 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username when checking for
 751 group membership</td></tr>
 752 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPGroupAttributeIsDN on|off</code></td></tr>
 753 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPGroupAttributeIsDN on</code></td></tr>
 754 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 755 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 756 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 757 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 758 </table>
 759     <p>When set <code>on</code>, this directive says to use the
 760     distinguished name of the client username when checking for group
 761     membership.  Otherwise, the username will be used. For example,
 762     assume that the client sent the username <code>bjenson</code>,
 763     which corresponds to the LDAP DN <code>cn=Babs Jenson,
 764     o=Airius</code>. If this directive is set,
 765     <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will check if the group has
 766     <code>cn=Babs Jenson, o=Airius</code> as a member. If this
 767     directive is not set, then <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will
 768     check if the group has <code>bjenson</code> as a member.</p>
 769
 770 </div>
 771 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 772 <div class="directive-section"><h2><a name="AuthLDAPRemoteUserIsDN" id="AuthLDAPRemoteUserIsDN">AuthLDAPRemoteUserIsDN</a> <a name="authldapremoteuserisdn" id="authldapremoteuserisdn">Directive</a></h2>
 773 <table class="directive">
 774 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use the DN of the client username to set the REMOTE_USER
 775 environment variable</td></tr>
 776 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPRemoteUserIsDN on|off</code></td></tr>
 777 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthLDAPRemoteUserIsDN off</code></td></tr>
 778 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 779 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 780 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 781 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 782 </table>
 783     <p>If this directive is set to on, the value of the
 784     <code>REMOTE_USER</code> environment variable will be set to the full
 785     distinguished name of the authenticated user, rather than just
 786     the username that was passed by the client. It is turned off by
 787     default.</p>
 788
 789 </div>
 790 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 791 <div class="directive-section"><h2><a name="AuthLDAPUrl" id="AuthLDAPUrl">AuthLDAPUrl</a> <a name="authldapurl" id="authldapurl">Directive</a></h2>
 792 <table class="directive">
 793 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>URL specifying the LDAP search parameters</td></tr>
 794 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthLDAPUrl <em>url</em></code></td></tr>
 795 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 796 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 797 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
 798 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_auth_ldap</td></tr>
 799 </table>
 800     <p>An RFC 2255 URL which specifies the LDAP search parameters
 801     to use. The syntax of the URL is</p>
 802 <div class="example"><p><code>ldap://host:port/basedn?attribute?scope?filter</code></p></div>
 803
 804 <dl>
 805 <dt>ldap</dt>
 806
 807         <dd>For regular ldap, use the
 808         string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
 809         instead. Secure LDAP is only available if Apache was linked
 810         to an LDAP library with SSL support.</dd>
 811
 812 <dt>host:port</dt>
 813
 814         <dd>
 815           <p>The name/port of the ldap server (defaults to
 816           <code>localhost:389</code> for <code>ldap</code>, and
 817           <code>localhost:636</code> for <code>ldaps</code>). To
 818           specify multiple, redundant LDAP servers, just list all
 819           servers, separated by spaces. <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code>
 820           will try connecting to each server in turn, until it makes a
 821           successful connection.</p>
 822
 823           <p>Once a connection has been made to a server, that
 824           connection remains active for the life of the
 825           <code>httpd</code> process, or until the LDAP server goes
 826           down.</p>
 827
 828           <p>If the LDAP server goes down and breaks an existing
 829           connection, <code class="module"><a href="../mod/mod_auth_ldap.html">mod_auth_ldap</a></code> will attempt to
 830           re-connect, starting with the primary server, and trying
 831           each redundant server in turn. Note that this is different
 832           than a true round-robin search.</p>
 833         </dd>
 834
 835 <dt>basedn</dt>
 836
 837         <dd>The DN of the branch of the
 838         directory where all searches should start from. At the very
 839         least, this must be the top of your directory tree, but
 840         could also specify a subtree in the directory.</dd>
 841
 842 <dt>attribute</dt>
 843
 844         <dd>The attribute to search for.
 845         Although RFC 2255 allows a comma-separated list of
 846         attributes, only the first attribute will be used, no
 847         matter how many are provided. If no attributes are
 848         provided, the default is to use <code>uid</code>. It's a good
 849         idea to choose an attribute that will be unique across all
 850         entries in the subtree you will be using.</dd>
 851
 852 <dt>scope</dt>
 853
 854         <dd>The scope of the search. Can be either <code>one</code> or
 855         <code>sub</code>. Note that a scope of <code>base</code> is
 856         also supported by RFC 2255, but is not supported by this
 857         module. If the scope is not provided, or if <code>base</code> scope
 858         is specified, the default is to use a scope of
 859         <code>sub</code>.</dd>
 860
 861 <dt>filter</dt>
 862
 863         <dd>A valid LDAP search filter. If
 864         not provided, defaults to <code>(objectClass=*)</code>, which
 865         will search for all objects in the tree. Filters are
 866         limited to approximately 8000 characters (the definition of
 867         <code>MAX_STRING_LEN</code> in the Apache source code). This
 868         should be than sufficient for any application.</dd>
 869 </dl>
 870
 871     <p>When doing searches, the attribute, filter and username passed
 872     by the HTTP client are combined to create a search filter that
 873     looks like
 874     <code>(&amp;(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
 875
 876     <p>For example, consider an URL of
 877     <code>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</code>. When
 878     a client attempts to connect using a username of <code>Babs
 879     Jenson</code>, the resulting search filter will be
 880     <code>(&amp;(posixid=*)(cn=Babs Jenson))</code>.</p>
 881
 882     <p>See above for examples of <code class="directive"><a href="#authldapurl">AuthLDAPURL</a></code> URLs.</p>
 883
 884 </div>
 885 </div>
 886 <div class="bottomlang">
 887 <p><span>Available Languages: </span><a href="../en/mod/mod_auth_ldap.html" title="English">&nbsp;en&nbsp;</a></p>
 888 </div><div id="footer">
 889 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 890 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 891 </body></html>