granicus.if.org Git - apache/blob - docs/manual/mod/mod_authnz_ldap.xml

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