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  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  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.</p>
 305 </section>
 306
 307 <section id="requser"><title>require ldap-user</title>
 308
 309     <p>The <code>require ldap-user</code> directive specifies what
 310     usernames can access the resource. Once
 311     <module>mod_authnz_ldap</module> has retrieved a unique DN from the
 312     directory, it does an LDAP compare operation using the username
 313     specified in the <code>require ldap-user</code> to see if that username
 314     is part of the just-fetched LDAP entry.  Multiple users can be
 315     granted access by putting multiple usernames on the line,
 316     separated with spaces. If a username has a space in it, then it
 317     must be surrounded with double quotes. Multiple users can also be
 318     granted access by using multiple <code>require ldap-user</code>
 319     directives, with one user per line. For example, with a <directive
 320     module="mod_authnz_ldap">AuthLDAPURL</directive> of
 321     <code>ldap://ldap/o=Airius?cn</code> (i.e., <code>cn</code> is
 322     used for searches), the following require directives could be used
 323     to restrict access:</p>
 324 <example>
 325 require ldap-user "Barbara Jenson"<br />
 326 require ldap-user "Fred User"<br />
 327 require ldap-user "Joe Manager"<br />
 328 </example>
 329
 330     <p>Because of the way that <module>mod_authnz_ldap</module> handles this
 331     directive, Barbara Jenson could sign on as <em>Barbara
 332     Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
 333     she has in her LDAP entry. Only the single <code>require
 334     ldap-user</code> line is needed to support all values of the attribute
 335     in the user's entry.</p>
 336
 337     <p>If the <code>uid</code> attribute was used instead of the
 338     <code>cn</code> attribute in the URL above, the above three lines
 339     could be condensed to</p>
 340 <example>require ldap-user bjenson fuser jmanager</example>
 341 </section>
 342
 343 <section id="reqgroup"><title>require ldap-group</title>
 344
 345     <p>This directive specifies an LDAP group whose members are
 346     allowed access. It takes the distinguished name of the LDAP
 347     group. Note: Do not surround the group name with quotes.
 348     For example, assume that the following entry existed in
 349     the LDAP directory:</p>
 350 <example>
 351 dn: cn=Administrators, o=Airius<br />
 352 objectClass: groupOfUniqueNames<br />
 353 uniqueMember: cn=Barbara Jenson, o=Airius<br />
 354 uniqueMember: cn=Fred User, o=Airius<br />
 355 </example>
 356
 357     <p>The following directive would grant access to both Fred and
 358     Barbara:</p>
 359 <example>require ldap-group cn=Administrators, o=Airius</example>
 360
 361     <p>Behavior of this directive is modified by the <directive
 362     module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive> and
 363     <directive
 364     module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive>
 365     directives.</p>
 366 </section>
 367
 368 <section id="reqdn"><title>require ldap-dn</title>
 369
 370     <p>The <code>require ldap-dn</code> directive allows the administrator
 371     to grant access based on distinguished names. It specifies a DN
 372     that must match for access to be granted. If the distinguished
 373     name that was retrieved from the directory server matches the
 374     distinguished name in the <code>require ldap-dn</code>, then
 375     authorization is granted. Note: do not surround the distinguished
 376     name with quotes.</p>
 377
 378     <p>The following directive would grant access to a specific
 379     DN:</p>
 380 <example>require ldap-dn cn=Barbara Jenson, o=Airius</example>
 381
 382     <p>Behavior of this directive is modified by the <directive
 383     module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive>
 384     directive.</p>
 385 </section>
 386
 387 <section id="reqattribute"><title>require ldap-attribute</title>
 388
 389     <p>The <code>require ldap-attribute</code> directive allows the
 390     administrator to grant access based on attributes of the authenticated
 391     user in the LDAP directory.  If the attribute in the directory
 392     matches the value given in the configuration, access is granted.</p>
 393
 394     <p>The following directive would grant access to anyone with
 395     the attribute employeeType = active</p>
 396
 397     <example>require ldap-attribute employeeType=active</example>
 398
 399     <p>Multiple attribute/value pairs can be specified on the same line
 400     separated by spaces or they can be specified in multiple
 401     <code>require ldap-attribute</code> directives. The effect of listing
 402     multiple attribute/values pairs is an OR operation. Access will be
 403     granted if any of the listed attribute values match the value of the
 404     corresponding attribute in the user object. If the value of the
 405     attribute contains a space, only the value must be within double quotes.</p>
 406
 407     <p>The following directive would grant access to anyone with
 408     the city attribute equal to "San Jose" or status equal to "Active"</p>
 409
 410     <example>require ldap-attribute city="San Jose" status=active</example>
 411
 412 </section>
 413
 414 <section id="reqfilter"><title>require ldap-filter</title>
 415
 416     <p>The <code>require ldap-filter</code> directive allows the
 417     administrator to grant access based on a complex LDAP search filter.
 418     If the dn returned by the filter search matches the authenticated user
 419     dn, access is granted.</p>
 420
 421     <p>The following directive would grant access to anyone having a cell phone
 422     and is in the marketing department</p>
 423
 424     <example>require ldap-filter &amp;(cell=*)(department=marketing)</example>
 425
 426     <p>The difference between the <code>require ldap-filter</code> directive and the
 427     <code>require ldap-attribute</code> directive is that <code>ldap-filter</code>
 428     performs a search operation on the LDAP directory using the specified search
 429     filter rather than a simple attribute comparison. If a simple attribute
 430     comparison is all that is required, the comparison operation performed by
 431     <code>ldap-attribute</code> will be faster than the search operation
 432     used by <code>ldap-filter</code> especially within a large directory.</p>
 433
 434 </section>
 435
 436 </section>
 437
 438 <section id="examples"><title>Examples</title>
 439
 440     <ul>
 441       <li>
 442         Grant access to anyone who exists in the LDAP directory,
 443         using their UID for searches.
 444 <example>
 445 AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)<br />
 446 require valid-user
 447 </example>
 448       </li>
 449
 450       <li>
 451         The next example is the same as above; but with the fields
 452         that have useful defaults omitted. Also, note the use of a
 453         redundant LDAP server.
 454 <example>AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius<br />
 455 require valid-user
 456 </example>
 457       </li>
 458
 459       <li>
 460         The next example is similar to the previous one, but it
 461         uses the common name instead of the UID. Note that this
 462         could be problematical if multiple people in the directory
 463         share the same <code>cn</code>, because a search on <code>cn</code>
 464         <strong>must</strong> return exactly one entry. That's why
 465         this approach is not recommended: it's a better idea to
 466         choose an attribute that is guaranteed unique in your
 467         directory, such as <code>uid</code>.
 468 <example>
 469 AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn<br />
 470 require valid-user
 471 </example>
 472       </li>
 473
 474       <li>
 475         Grant access to anybody in the Administrators group. The
 476         users must authenticate using their UID.
 477 <example>
 478 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid<br />
 479 require ldap-group cn=Administrators, o=Airius
 480 </example>
 481       </li>
 482
 483       <li>
 484         The next example assumes that everyone at Airius who
 485         carries an alphanumeric pager will have an LDAP attribute
 486         of <code>qpagePagerID</code>. The example will grant access
 487         only to people (authenticated via their UID) who have
 488         alphanumeric pagers:
 489 <example>
 490 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)<br />
 491 require valid-user
 492 </example>
 493       </li>
 494
 495       <li>
 496         <p>The next example demonstrates the power of using filters
 497         to accomplish complicated administrative requirements.
 498         Without filters, it would have been necessary to create a
 499         new LDAP group and ensure that the group's members remain
 500         synchronized with the pager users. This becomes trivial
 501         with filters. The goal is to grant access to anyone who has
 502         a pager, plus grant access to Joe Manager, who doesn't
 503         have a pager, but does need to access the same
 504         resource:</p>
 505 <example>
 506 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))<br />
 507 require valid-user
 508 </example>
 509
 510         <p>This last may look confusing at first, so it helps to
 511         evaluate what the search filter will look like based on who
 512         connects, as shown below.  If
 513         Fred User connects as <code>fuser</code>, the filter would look
 514         like</p>
 515
 516         <example>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</example>
 517
 518         <p>The above search will only succeed if <em>fuser</em> has a
 519         pager. When Joe Manager connects as <em>jmanager</em>, the
 520         filter looks like</p>
 521
 522         <example>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</example>
 523
 524         <p>The above search will succeed whether <em>jmanager</em>
 525         has a pager or not.</p>
 526       </li>
 527     </ul>
 528 </section>
 529
 530 <section id="usingtls"><title>Using TLS</title>
 531
 532     <p>To use TLS, see the <module>mod_ldap</module> directives <directive
 533     module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
 534     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
 535     module="mod_ldap">LDAPTrustedMode</directive>.</p>
 536
 537     <p>An optional second parameter can be added to the
 538     <directive module="mod_authnz_ldap">AuthLDAPURL</directive> to override
 539     the default connection type set by <directive module="mod_ldap">LDAPTrustedMode</directive>.
 540     This will allow the connection established by an <em>ldap://</em> Url
 541     to be upgraded to a secure connection on the same port.</p>
 542 </section>
 543
 544 <section id="usingssl"><title>Using SSL</title>
 545
 546     <p>To use SSL, see the <module>mod_ldap</module> directives <directive
 547     module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
 548     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
 549     module="mod_ldap">LDAPTrustedMode</directive>.</p>
 550
 551     <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
 552     <directive module="mod_authnz_ldap">AuthLDAPURL</directive>
 553     directive, instead of <em>ldap://</em>.</p>
 554 </section>
 555
 556 <section id="frontpage"><title>Using Microsoft
 557     FrontPage with mod_authnz_ldap</title>
 558
 559     <p>Normally, FrontPage uses FrontPage-web-specific user/group
 560     files (i.e., the <module>mod_authn_file</module> and
 561     <module>mod_authz_groupfile</module> modules) to handle all
 562     authentication. Unfortunately, it is not possible to just
 563     change to LDAP authentication by adding the proper directives,
 564     because it will break the <em>Permissions</em> forms in
 565     the FrontPage client, which attempt to modify the standard
 566     text-based authorization files.</p>
 567
 568     <p>Once a FrontPage web has been created, adding LDAP
 569     authentication to it is a matter of adding the following
 570     directives to <em>every</em> <code>.htaccess</code> file
 571     that gets created in the web</p>
 572 <example><pre>
 573 AuthLDAPURL            "the url"
 574 AuthGroupFile <em>mygroupfile</em>
 575 require group <em>mygroupfile</em>
 576 </pre></example>
 577
 578 <section id="howitworks"><title>How It Works</title>
 579
 580     <p>FrontPage restricts access to a web by adding the <code>require
 581     valid-user</code> directive to the <code>.htaccess</code>
 582     files. The <code>require valid-user</code> directive will succeed for
 583     any user who is valid <em>as far as LDAP is
 584     concerned</em>. This means that anybody who has an entry in
 585     the LDAP directory is considered a valid user, whereas FrontPage
 586     considers only those people in the local user file to be
 587     valid. By substituting the ldap-group with group file authorization,
 588     Apache is allowed to consult the local user file (which is managed by
 589     FrontPage) - instead of LDAP - when handling authorizing the user.</p>
 590
 591     <p>Once directives have been added as specified above,
 592     FrontPage users will be able to perform all management
 593     operations from the FrontPage client.</p>
 594 </section>
 595
 596 <section id="fpcaveats"><title>Caveats</title>
 597
 598     <ul>
 599       <li>When choosing the LDAP URL, the attribute to use for
 600       authentication should be something that will also be valid
 601       for putting into a <module>mod_authn_file</module> user file.
 602       The user ID is ideal for this.</li>
 603
 604       <li>When adding users via FrontPage, FrontPage administrators
 605       should choose usernames that already exist in the LDAP
 606       directory (for obvious reasons). Also, the password that the
 607       administrator enters into the form is ignored, since Apache
 608       will actually be authenticating against the password in the
 609       LDAP database, and not against the password in the local user
 610       file. This could cause confusion for web administrators.</li>
 611
 612       <!-- XXX is that true? was mod_auth before the aaa change -->
 613       <li>Apache must be compiled with <module>mod_auth_basic</module>,
 614       <module>mod_authn_file</module> and
 615       <module>mod_authz_groupfile</module> in order to
 616       use FrontPage support. This is because Apache will still use
 617       the <module>mod_authz_groupfile</module> group file for determine
 618       the extent of a user's access to the FrontPage web.</li>
 619
 620       <li>The directives must be put in the <code>.htaccess</code>
 621       files. Attempting to put them inside <directive module="core"
 622       type="section">Location</directive> or <directive module="core"
 623       type="section">Directory</directive> directives won't work. This
 624       is because <module>mod_authnz_ldap</module> has to be able to grab
 625       the <directive module="mod_authn_file">AuthGroupFile</directive>
 626       directive that is found in FrontPage <code>.htaccess</code>
 627       files so that it knows where to look for the valid user list. If
 628       the <module>mod_authnz_ldap</module> directives aren't in the same
 629       <code>.htaccess</code> file as the FrontPage directives, then
 630       the hack won't work, because <module>mod_authnz_ldap</module> will
 631       never get a chance to process the <code>.htaccess</code> file,
 632       and won't be able to find the FrontPage-managed user file.</li>
 633     </ul>
 634 </section>
 635 </section>
 636
 637 <directivesynopsis>
 638 <name>AuthLDAPBindDN</name>
 639 <description>Optional DN to use in binding to the LDAP server</description>
 640 <syntax>AuthLDAPBindDN <em>distinguished-name</em></syntax>
 641 <contextlist><context>directory</context><context>.htaccess</context>
 642 </contextlist>
 643 <override>AuthConfig</override>
 644
 645 <usage>
 646     <p>An optional DN used to bind to the server when searching for
 647     entries. If not provided, <module>mod_authnz_ldap</module> will use
 648     an anonymous bind.</p>
 649 </usage>
 650 </directivesynopsis>
 651
 652 <directivesynopsis>
 653 <name>AuthLDAPBindPassword</name>
 654 <description>Password used in conjuction with the bind DN</description>
 655 <syntax>AuthLDAPBindPassword <em>password</em></syntax>
 656 <contextlist><context>directory</context><context>.htaccess</context>
 657 </contextlist>
 658 <override>AuthConfig</override>
 659
 660 <usage>
 661     <p>A bind password to use in conjunction with the bind DN. Note
 662     that the bind password is probably sensitive data, and should be
 663     properly protected. You should only use the <directive
 664     module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
 665     module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
 666     absolutely need them to search the directory.</p>
 667 </usage>
 668 </directivesynopsis>
 669
 670 <directivesynopsis>
 671 <name>AuthLDAPCharsetConfig</name>
 672 <description>Language to charset conversion configuration file</description>
 673 <syntax>AuthLDAPCharsetConfig <em>file-path</em></syntax>
 674 <contextlist><context>server config</context>
 675 </contextlist>
 676
 677 <usage>
 678     <p>The <directive>AuthLDAPCharsetConfig</directive> directive sets the location
 679     of the language to charset conversion configuration file. <var>File-path</var> is relative
 680     to the <directive module="core">ServerRoot</directive>. This file specifies
 681     the list of language extensions to character sets.
 682     Most administrators use the provided <code>charset.conv</code>
 683     file, which associates common language extensions to character sets.</p>
 684
 685     <p>The file contains lines in the following format:</p>
 686
 687     <example>
 688       <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
 689     </example>
 690
 691     <p>The case of the extension does not matter. Blank lines, and lines
 692     beginning with a hash character (<code>#</code>) are ignored.</p>
 693 </usage>
 694 </directivesynopsis>
 695
 696 <directivesynopsis>
 697 <name>AuthLDAPCompareDNOnServer</name>
 698 <description>Use the LDAP server to compare the DNs</description>
 699 <syntax>AuthLDAPCompareDNOnServer on|off</syntax>
 700 <default>AuthLDAPCompareDNOnServer on</default>
 701 <contextlist><context>directory</context><context>.htaccess</context>
 702 </contextlist>
 703 <override>AuthConfig</override>
 704
 705 <usage>
 706     <p>When set, <module>mod_authnz_ldap</module> will use the LDAP
 707     server to compare the DNs. This is the only foolproof way to
 708     compare DNs.  <module>mod_authnz_ldap</module> will search the
 709     directory for the DN specified with the <a
 710     href="#reqdn"><code>require dn</code></a> directive, then,
 711     retrieve the DN and compare it with the DN retrieved from the user
 712     entry. If this directive is not set,
 713     <module>mod_authnz_ldap</module> simply does a string comparison. It
 714     is possible to get false negatives with this approach, but it is
 715     much faster. Note the <module>mod_ldap</module> cache can speed up
 716     DN comparison in most situations.</p>
 717 </usage>
 718 </directivesynopsis>
 719
 720 <directivesynopsis>
 721 <name>AuthLDAPDereferenceAliases</name>
 722 <description>When will the module de-reference aliases</description>
 723 <syntax>AuthLDAPDereferenceAliases never|searching|finding|always</syntax>
 724 <default>AuthLDAPDereferenceAliases Always</default>
 725 <contextlist><context>directory</context><context>.htaccess</context>
 726 </contextlist>
 727 <override>AuthConfig</override>
 728
 729 <usage>
 730     <p>This directive specifies when <module>mod_authnz_ldap</module> will
 731     de-reference aliases during LDAP operations. The default is
 732     <code>always</code>.</p>
 733 </usage>
 734 </directivesynopsis>
 735
 736 <directivesynopsis>
 737 <name>AuthLDAPGroupAttribute</name>
 738 <description>LDAP attributes used to check for group membership</description>
 739 <syntax>AuthLDAPGroupAttribute <em>attribute</em></syntax>
 740 <contextlist><context>directory</context><context>.htaccess</context>
 741 </contextlist>
 742 <override>AuthConfig</override>
 743
 744 <usage>
 745     <p>This directive specifies which LDAP attributes are used to
 746     check for group membership. Multiple attributes can be used by
 747     specifying this directive multiple times. If not specified,
 748     then <module>mod_authnz_ldap</module> uses the <code>member</code> and
 749     <code>uniquemember</code> attributes.</p>
 750 </usage>
 751 </directivesynopsis>
 752
 753 <directivesynopsis>
 754 <name>AuthLDAPGroupAttributeIsDN</name>
 755 <description>Use the DN of the client username when checking for
 756 group membership</description>
 757 <syntax>AuthLDAPGroupAttributeIsDN on|off</syntax>
 758 <default>AuthLDAPGroupAttributeIsDN on</default>
 759 <contextlist><context>directory</context><context>.htaccess</context>
 760 </contextlist>
 761 <override>AuthConfig</override>
 762
 763 <usage>
 764     <p>When set <code>on</code>, this directive says to use the
 765     distinguished name of the client username when checking for group
 766     membership.  Otherwise, the username will be used. For example,
 767     assume that the client sent the username <code>bjenson</code>,
 768     which corresponds to the LDAP DN <code>cn=Babs Jenson,
 769     o=Airius</code>. If this directive is set,
 770     <module>mod_authnz_ldap</module> will check if the group has
 771     <code>cn=Babs Jenson, o=Airius</code> as a member. If this
 772     directive is not set, then <module>mod_authnz_ldap</module> will
 773     check if the group has <code>bjenson</code> as a member.</p>
 774 </usage>
 775 </directivesynopsis>
 776
 777 <directivesynopsis>
 778 <name>AuthLDAPRemoteUserIsDN</name>
 779 <description>Use the DN of the client username to set the REMOTE_USER
 780 environment variable</description>
 781 <syntax>AuthLDAPRemoteUserIsDN on|off</syntax>
 782 <default>AuthLDAPRemoteUserIsDN off</default>
 783 <contextlist><context>directory</context><context>.htaccess</context>
 784 </contextlist>
 785 <override>AuthConfig</override>
 786
 787 <usage>
 788     <p>If this directive is set to on, the value of the
 789     <code>REMOTE_USER</code> environment variable will be set to the full
 790     distinguished name of the authenticated user, rather than just
 791     the username that was passed by the client. It is turned off by
 792     default.</p>
 793 </usage>
 794 </directivesynopsis>
 795
 796 <directivesynopsis>
 797 <name>AuthLDAPUrl</name>
 798 <description>URL specifying the LDAP search parameters</description>
 799 <syntax>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></syntax>
 800 <contextlist><context>directory</context><context>.htaccess</context>
 801 </contextlist>
 802 <override>AuthConfig</override>
 803
 804 <usage>
 805     <p>An RFC 2255 URL which specifies the LDAP search parameters
 806     to use. The syntax of the URL is</p>
 807 <example>ldap://host:port/basedn?attribute?scope?filter</example>
 808
 809 <dl>
 810 <dt>ldap</dt>
 811
 812         <dd>For regular ldap, use the
 813         string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
 814         instead. Secure LDAP is only available if Apache was linked
 815         to an LDAP library with SSL support.</dd>
 816
 817 <dt>host:port</dt>
 818
 819         <dd>
 820           <p>The name/port of the ldap server (defaults to
 821           <code>localhost:389</code> for <code>ldap</code>, and
 822           <code>localhost:636</code> for <code>ldaps</code>). To
 823           specify multiple, redundant LDAP servers, just list all
 824           servers, separated by spaces. <module>mod_authnz_ldap</module>
 825           will try connecting to each server in turn, until it makes a
 826           successful connection.</p>
 827
 828           <p>Once a connection has been made to a server, that
 829           connection remains active for the life of the
 830           <program>httpd</program> process, or until the LDAP server goes
 831           down.</p>
 832
 833           <p>If the LDAP server goes down and breaks an existing
 834           connection, <module>mod_authnz_ldap</module> will attempt to
 835           re-connect, starting with the primary server, and trying
 836           each redundant server in turn. Note that this is different
 837           than a true round-robin search.</p>
 838         </dd>
 839
 840 <dt>basedn</dt>
 841
 842         <dd>The DN of the branch of the
 843         directory where all searches should start from. At the very
 844         least, this must be the top of your directory tree, but
 845         could also specify a subtree in the directory.</dd>
 846
 847 <dt>attribute</dt>
 848
 849         <dd>The attribute to search for.
 850         Although RFC 2255 allows a comma-separated list of
 851         attributes, only the first attribute will be used, no
 852         matter how many are provided. If no attributes are
 853         provided, the default is to use <code>uid</code>. It's a good
 854         idea to choose an attribute that will be unique across all
 855         entries in the subtree you will be using.</dd>
 856
 857 <dt>scope</dt>
 858
 859         <dd>The scope of the search. Can be either <code>one</code> or
 860         <code>sub</code>. Note that a scope of <code>base</code> is
 861         also supported by RFC 2255, but is not supported by this
 862         module. If the scope is not provided, or if <code>base</code> scope
 863         is specified, the default is to use a scope of
 864         <code>sub</code>.</dd>
 865
 866 <dt>filter</dt>
 867
 868         <dd>A valid LDAP search filter. If
 869         not provided, defaults to <code>(objectClass=*)</code>, which
 870         will search for all objects in the tree. Filters are
 871         limited to approximately 8000 characters (the definition of
 872         <code>MAX_STRING_LEN</code> in the Apache source code). This
 873         should be than sufficient for any application.</dd>
 874 </dl>
 875
 876     <p>When doing searches, the attribute, filter and username passed
 877     by the HTTP client are combined to create a search filter that
 878     looks like
 879     <code>(&amp;(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
 880
 881     <p>For example, consider an URL of
 882     <code>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</code>. When
 883     a client attempts to connect using a username of <code>Babs
 884     Jenson</code>, the resulting search filter will be
 885     <code>(&amp;(posixid=*)(cn=Babs Jenson))</code>.</p>
 886
 887     <p>An optional parameter can be added to allow the LDAP Url to override
 888     the connection type.  This parameter can be one of the following:</p>
 889
 890 <dl>
 891     <dt>NONE</dt>
 892         <dd>Establish an unsecure connection on the default LDAP port. This
 893         is the same as <code>ldap://</code> on port 389.</dd>
 894     <dt>SSL</dt>
 895         <dd>Establish a secure connection on the default secure LDAP port.
 896         This is the same as <code>ldaps://</code></dd>
 897     <dt>TLS | STARTTLS</dt>
 898         <dd>Establish an upgraded secure connection on the default LDAP port.
 899         This connection will be initiated on port 389 by default and then
 900         upgraded to a secure connection on the same port.</dd>
 901 </dl>
 902
 903     <p>See above for examples of <directive
 904     module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>
 905 </usage>
 906 </directivesynopsis>
 907
 908 </modulesynopsis>