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">LDAPTrustedClientCert</directive>, <directive
 536     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
 537     module="mod_ldap">LDAPTrustedMode</directive>.</p>
 538
 539     <p>An optional second parameter can be added to the
 540     <directive module="mod_authnz_ldap">AuthLDAPURL</directive> to override
 541     the default connection type set by <directive module="mod_ldap">LDAPTrustedMode</directive>.
 542     This will allow the connection established by an <em>ldap://</em> Url
 543     to be upgraded to a secure connection on the same port.</p>
 544 </section>
 545
 546 <section id="usingssl"><title>Using SSL</title>
 547
 548     <p>To use SSL, see the <module>mod_ldap</module> directives <directive
 549     module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
 550     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
 551     module="mod_ldap">LDAPTrustedMode</directive>.</p>
 552
 553     <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
 554     <directive module="mod_authnz_ldap">AuthLDAPURL</directive>
 555     directive, instead of <em>ldap://</em>.</p>
 556 </section>
 557
 558 <section id="frontpage"><title>Using Microsoft
 559     FrontPage with mod_authnz_ldap</title>
 560
 561     <p>Normally, FrontPage uses FrontPage-web-specific user/group
 562     files (i.e., the <module>mod_authn_file</module> and
 563     <module>mod_authz_groupfile</module> modules) to handle all
 564     authentication. Unfortunately, it is not possible to just
 565     change to LDAP authentication by adding the proper directives,
 566     because it will break the <em>Permissions</em> forms in
 567     the FrontPage client, which attempt to modify the standard
 568     text-based authorization files.</p>
 569
 570     <p>Once a FrontPage web has been created, adding LDAP
 571     authentication to it is a matter of adding the following
 572     directives to <em>every</em> <code>.htaccess</code> file
 573     that gets created in the web</p>
 574 <example><pre>
 575 AuthLDAPURL            "the url"
 576 AuthzLDAPAuthoritative off
 577 AuthGroupFile <em>mygroupfile</em>
 578 require group <em>mygroupfile</em>
 579 </pre></example>
 580
 581     <p><directive module="mod_authnz_ldap">AuthzLDAPAuthoritative</directive>
 582     must be off to allow <module>mod_authnz_ldap</module> to decline group
 583     authentication so that Apache will fall back to file
 584     authentication for checking group membership. This allows the
 585     FrontPage-managed group file to be used.</p>
 586
 587 <section id="howitworks"><title>How It Works</title>
 588
 589     <p>FrontPage restricts access to a web by adding the <code>require
 590     valid-user</code> directive to the <code>.htaccess</code>
 591     files. The <code>require valid-user</code> directive will succeed for
 592     any user who is valid <em>as far as LDAP is
 593     concerned</em>. This means that anybody who has an entry in
 594     the LDAP directory is considered a valid user, whereas FrontPage
 595     considers only those people in the local user file to be
 596     valid. By substituting the ldap-group with group file authorization,
 597     Apache is allowed to consult the local user file (which is managed by
 598     FrontPage) - instead of LDAP - when handling authorizing the user.</p>
 599
 600     <p>Once directives have been added as specified above,
 601     FrontPage users will be able to perform all management
 602     operations from the FrontPage client.</p>
 603 </section>
 604
 605 <section id="fpcaveats"><title>Caveats</title>
 606
 607     <ul>
 608       <li>When choosing the LDAP URL, the attribute to use for
 609       authentication should be something that will also be valid
 610       for putting into a <module>mod_authn_file</module> user file.
 611       The user ID is ideal for this.</li>
 612
 613       <li>When adding users via FrontPage, FrontPage administrators
 614       should choose usernames that already exist in the LDAP
 615       directory (for obvious reasons). Also, the password that the
 616       administrator enters into the form is ignored, since Apache
 617       will actually be authenticating against the password in the
 618       LDAP database, and not against the password in the local user
 619       file. This could cause confusion for web administrators.</li>
 620
 621       <!-- XXX is that true? was mod_auth before the aaa change -->
 622       <li>Apache must be compiled with <module>mod_auth_basic</module>,
 623       <module>mod_authn_file</module> and
 624       <module>mod_authz_groupfile</module> in order to
 625       use FrontPage support. This is because Apache will still use
 626       the <module>mod_authz_groupfile</module> group file for determine
 627       the extent of a user's access to the FrontPage web.</li>
 628
 629       <li>The directives must be put in the <code>.htaccess</code>
 630       files. Attempting to put them inside <directive module="core"
 631       type="section">Location</directive> or <directive module="core"
 632       type="section">Directory</directive> directives won't work. This
 633       is because <module>mod_authnz_ldap</module> has to be able to grab
 634       the <directive module="mod_authn_file">AuthGroupFile</directive>
 635       directive that is found in FrontPage <code>.htaccess</code>
 636       files so that it knows where to look for the valid user list. If
 637       the <module>mod_authnz_ldap</module> directives aren't in the same
 638       <code>.htaccess</code> file as the FrontPage directives, then
 639       the hack won't work, because <module>mod_authnz_ldap</module> will
 640       never get a chance to process the <code>.htaccess</code> file,
 641       and won't be able to find the FrontPage-managed user file.</li>
 642     </ul>
 643 </section>
 644 </section>
 645
 646 <directivesynopsis>
 647 <name>AuthzLDAPAuthoritative</name>
 648 <description>Prevent other authentication modules from
 649 authenticating the user if this one fails</description>
 650 <syntax>AuthzLDAPAuthoritative on|off</syntax>
 651 <default>AuthzLDAPAuthoritative on</default>
 652 <contextlist><context>directory</context><context>.htaccess</context>
 653 </contextlist>
 654 <override>AuthConfig</override>
 655
 656 <usage>
 657     <p>Set to <code>off</code> if this module should let other
 658     authentication modules attempt to authenticate the user, should
 659     authentication with this module fail. Control is only passed on
 660     to lower modules if there is no DN or rule that matches the
 661     supplied user name (as passed by the client).</p>
 662 </usage>
 663 </directivesynopsis>
 664
 665 <directivesynopsis>
 666 <name>AuthLDAPBindDN</name>
 667 <description>Optional DN to use in binding to the LDAP server</description>
 668 <syntax>AuthLDAPBindDN <em>distinguished-name</em></syntax>
 669 <contextlist><context>directory</context><context>.htaccess</context>
 670 </contextlist>
 671 <override>AuthConfig</override>
 672
 673 <usage>
 674     <p>An optional DN used to bind to the server when searching for
 675     entries. If not provided, <module>mod_authnz_ldap</module> will use
 676     an anonymous bind.</p>
 677 </usage>
 678 </directivesynopsis>
 679
 680 <directivesynopsis>
 681 <name>AuthLDAPBindPassword</name>
 682 <description>Password used in conjuction with the bind DN</description>
 683 <syntax>AuthLDAPBindPassword <em>password</em></syntax>
 684 <contextlist><context>directory</context><context>.htaccess</context>
 685 </contextlist>
 686 <override>AuthConfig</override>
 687
 688 <usage>
 689     <p>A bind password to use in conjunction with the bind DN. Note
 690     that the bind password is probably sensitive data, and should be
 691     properly protected. You should only use the <directive
 692     module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
 693     module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
 694     absolutely need them to search the directory.</p>
 695 </usage>
 696 </directivesynopsis>
 697
 698 <directivesynopsis>
 699 <name>AuthLDAPCharsetConfig</name>
 700 <description>Language to charset conversion configuration file</description>
 701 <syntax>AuthLDAPCharsetConfig <em>file-path</em></syntax>
 702 <contextlist><context>server config</context>
 703 </contextlist>
 704
 705 <usage>
 706     <p>The <directive>AuthLDAPCharsetConfig</directive> directive sets the location
 707     of the language to charset conversion configuration file. <var>File-path</var> is relative
 708     to the <directive module="core">ServerRoot</directive>. This file specifies
 709     the list of language extensions to character sets.
 710     Most administrators use the provided <code>charset.conv</code>
 711     file, which associates common language extensions to character sets.</p>
 712
 713     <p>The file contains lines in the following format:</p>
 714
 715     <example>
 716       <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
 717     </example>
 718
 719     <p>The case of the extension does not matter. Blank lines, and lines
 720     beginning with a hash character (<code>#</code>) are ignored.</p>
 721 </usage>
 722 </directivesynopsis>
 723
 724 <directivesynopsis>
 725 <name>AuthLDAPCompareDNOnServer</name>
 726 <description>Use the LDAP server to compare the DNs</description>
 727 <syntax>AuthLDAPCompareDNOnServer on|off</syntax>
 728 <default>AuthLDAPCompareDNOnServer on</default>
 729 <contextlist><context>directory</context><context>.htaccess</context>
 730 </contextlist>
 731 <override>AuthConfig</override>
 732
 733 <usage>
 734     <p>When set, <module>mod_authnz_ldap</module> will use the LDAP
 735     server to compare the DNs. This is the only foolproof way to
 736     compare DNs.  <module>mod_authnz_ldap</module> will search the
 737     directory for the DN specified with the <a
 738     href="#reqdn"><code>require dn</code></a> directive, then,
 739     retrieve the DN and compare it with the DN retrieved from the user
 740     entry. If this directive is not set,
 741     <module>mod_authnz_ldap</module> simply does a string comparison. It
 742     is possible to get false negatives with this approach, but it is
 743     much faster. Note the <module>mod_ldap</module> cache can speed up
 744     DN comparison in most situations.</p>
 745 </usage>
 746 </directivesynopsis>
 747
 748 <directivesynopsis>
 749 <name>AuthLDAPDereferenceAliases</name>
 750 <description>When will the module de-reference aliases</description>
 751 <syntax>AuthLDAPDereferenceAliases never|searching|finding|always</syntax>
 752 <default>AuthLDAPDereferenceAliases Always</default>
 753 <contextlist><context>directory</context><context>.htaccess</context>
 754 </contextlist>
 755 <override>AuthConfig</override>
 756
 757 <usage>
 758     <p>This directive specifies when <module>mod_authnz_ldap</module> will
 759     de-reference aliases during LDAP operations. The default is
 760     <code>always</code>.</p>
 761 </usage>
 762 </directivesynopsis>
 763
 764 <directivesynopsis>
 765 <name>AuthLDAPGroupAttribute</name>
 766 <description>LDAP attributes used to check for group membership</description>
 767 <syntax>AuthLDAPGroupAttribute <em>attribute</em></syntax>
 768 <contextlist><context>directory</context><context>.htaccess</context>
 769 </contextlist>
 770 <override>AuthConfig</override>
 771
 772 <usage>
 773     <p>This directive specifies which LDAP attributes are used to
 774     check for group membership. Multiple attributes can be used by
 775     specifying this directive multiple times. If not specified,
 776     then <module>mod_authnz_ldap</module> uses the <code>member</code> and
 777     <code>uniquemember</code> attributes.</p>
 778 </usage>
 779 </directivesynopsis>
 780
 781 <directivesynopsis>
 782 <name>AuthLDAPGroupAttributeIsDN</name>
 783 <description>Use the DN of the client username when checking for
 784 group membership</description>
 785 <syntax>AuthLDAPGroupAttributeIsDN on|off</syntax>
 786 <default>AuthLDAPGroupAttributeIsDN on</default>
 787 <contextlist><context>directory</context><context>.htaccess</context>
 788 </contextlist>
 789 <override>AuthConfig</override>
 790
 791 <usage>
 792     <p>When set <code>on</code>, this directive says to use the
 793     distinguished name of the client username when checking for group
 794     membership.  Otherwise, the username will be used. For example,
 795     assume that the client sent the username <code>bjenson</code>,
 796     which corresponds to the LDAP DN <code>cn=Babs Jenson,
 797     o=Airius</code>. If this directive is set,
 798     <module>mod_authnz_ldap</module> will check if the group has
 799     <code>cn=Babs Jenson, o=Airius</code> as a member. If this
 800     directive is not set, then <module>mod_authnz_ldap</module> will
 801     check if the group has <code>bjenson</code> as a member.</p>
 802 </usage>
 803 </directivesynopsis>
 804
 805 <directivesynopsis>
 806 <name>AuthLDAPRemoteUserIsDN</name>
 807 <description>Use the DN of the client username to set the REMOTE_USER
 808 environment variable</description>
 809 <syntax>AuthLDAPRemoteUserIsDN on|off</syntax>
 810 <default>AuthLDAPRemoteUserIsDN off</default>
 811 <contextlist><context>directory</context><context>.htaccess</context>
 812 </contextlist>
 813 <override>AuthConfig</override>
 814
 815 <usage>
 816     <p>If this directive is set to on, the value of the
 817     <code>REMOTE_USER</code> environment variable will be set to the full
 818     distinguished name of the authenticated user, rather than just
 819     the username that was passed by the client. It is turned off by
 820     default.</p>
 821 </usage>
 822 </directivesynopsis>
 823
 824 <directivesynopsis>
 825 <name>AuthLDAPUrl</name>
 826 <description>URL specifying the LDAP search parameters</description>
 827 <syntax>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></syntax>
 828 <contextlist><context>directory</context><context>.htaccess</context>
 829 </contextlist>
 830 <override>AuthConfig</override>
 831
 832 <usage>
 833     <p>An RFC 2255 URL which specifies the LDAP search parameters
 834     to use. The syntax of the URL is</p>
 835 <example>ldap://host:port/basedn?attribute?scope?filter</example>
 836
 837 <dl>
 838 <dt>ldap</dt>
 839
 840         <dd>For regular ldap, use the
 841         string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
 842         instead. Secure LDAP is only available if Apache was linked
 843         to an LDAP library with SSL support.</dd>
 844
 845 <dt>host:port</dt>
 846
 847         <dd>
 848           <p>The name/port of the ldap server (defaults to
 849           <code>localhost:389</code> for <code>ldap</code>, and
 850           <code>localhost:636</code> for <code>ldaps</code>). To
 851           specify multiple, redundant LDAP servers, just list all
 852           servers, separated by spaces. <module>mod_authnz_ldap</module>
 853           will try connecting to each server in turn, until it makes a
 854           successful connection.</p>
 855
 856           <p>Once a connection has been made to a server, that
 857           connection remains active for the life of the
 858           <program>httpd</program> process, or until the LDAP server goes
 859           down.</p>
 860
 861           <p>If the LDAP server goes down and breaks an existing
 862           connection, <module>mod_authnz_ldap</module> will attempt to
 863           re-connect, starting with the primary server, and trying
 864           each redundant server in turn. Note that this is different
 865           than a true round-robin search.</p>
 866         </dd>
 867
 868 <dt>basedn</dt>
 869
 870         <dd>The DN of the branch of the
 871         directory where all searches should start from. At the very
 872         least, this must be the top of your directory tree, but
 873         could also specify a subtree in the directory.</dd>
 874
 875 <dt>attribute</dt>
 876
 877         <dd>The attribute to search for.
 878         Although RFC 2255 allows a comma-separated list of
 879         attributes, only the first attribute will be used, no
 880         matter how many are provided. If no attributes are
 881         provided, the default is to use <code>uid</code>. It's a good
 882         idea to choose an attribute that will be unique across all
 883         entries in the subtree you will be using.</dd>
 884
 885 <dt>scope</dt>
 886
 887         <dd>The scope of the search. Can be either <code>one</code> or
 888         <code>sub</code>. Note that a scope of <code>base</code> is
 889         also supported by RFC 2255, but is not supported by this
 890         module. If the scope is not provided, or if <code>base</code> scope
 891         is specified, the default is to use a scope of
 892         <code>sub</code>.</dd>
 893
 894 <dt>filter</dt>
 895
 896         <dd>A valid LDAP search filter. If
 897         not provided, defaults to <code>(objectClass=*)</code>, which
 898         will search for all objects in the tree. Filters are
 899         limited to approximately 8000 characters (the definition of
 900         <code>MAX_STRING_LEN</code> in the Apache source code). This
 901         should be than sufficient for any application.</dd>
 902 </dl>
 903
 904     <p>When doing searches, the attribute, filter and username passed
 905     by the HTTP client are combined to create a search filter that
 906     looks like
 907     <code>(&amp;(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
 908
 909     <p>For example, consider an URL of
 910     <code>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</code>. When
 911     a client attempts to connect using a username of <code>Babs
 912     Jenson</code>, the resulting search filter will be
 913     <code>(&amp;(posixid=*)(cn=Babs Jenson))</code>.</p>
 914
 915     <p>An optional parameter can be added to allow the LDAP Url to override
 916     the connection type.  This parameter can be one of the following:</p>
 917
 918 <dl>
 919     <dt>NONE</dt>
 920         <dd>Establish an unsecure connection on the default LDAP port. This
 921         is the same as <code>ldap://</code> on port 389.</dd>
 922     <dt>SSL</dt>
 923         <dd>Establish a secure connection on the default secure LDAP port.
 924         This is the same as <code>ldaps://</code></dd>
 925     <dt>TLS | STARTTLS</dt>
 926         <dd>Establish an upgraded secure connection on the default LDAP port.
 927         This connection will be initiated on port 389 by default and then
 928         upgraded to a secure connection on the same port.</dd>
 929 </dl>
 930
 931     <p>See above for examples of <directive
 932     module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>
 933 </usage>
 934 </directivesynopsis>
 935
 936 </modulesynopsis>