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