2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Copyright 2004-2005 The Apache Software Foundation or its licensors,
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_authnz_ldap.xml.meta">
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>
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>
38 <p><module>mod_authnz_ldap</module> supports the following features:</p>
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>
48 <li>Complex authorization policies can be implemented by
49 representing the policy with LDAP filters.</li>
51 <li>Uses extensive caching of LDAP operations via <a
52 href="mod_ldap.html">mod_ldap</a>.</li>
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>
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>
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>
68 <section id="contents"><title>Contents</title>
72 <a href="#operation">Operation</a>
75 <li><a href="#authenphase">The Authentication
78 <li><a href="#authorphase">The Authorization
84 <a href="#requiredirectives">The require Directives</a>
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>
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>
101 <a href="#frontpage">Using Microsoft FrontPage with
102 <module>mod_authnz_ldap</module></a>
105 <li><a href="#howitworks">How It Works</a></li>
106 <li><a href="#fpcaveats">Caveats</a></li>
112 <section id="operation"><title>Operation</title>
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>
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>
132 <section id="authenphase"><title>The Authentication
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>
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>
150 <li>Search the directory using the generated filter. If the
151 search does not return exactly one entry, deny or decline
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>
160 <p>The following directives are used during the search/bind
164 <columnspec><column width=".3"/><column width=".7"/></columnspec>
166 <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive></td>
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>
174 <td><directive module="mod_authnz_ldap">AuthLDAPBindDN</directive></td>
176 <td>An optional DN to bind with
177 during the search phase.</td>
182 module="mod_authnz_ldap">AuthLDAPBindPassword</directive></td>
184 <td>An optional password to bind
185 with during the search phase.</td>
190 <section id="authorphase"><title>The Authorization Phase</title>
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>
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
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>
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>
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>
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>
226 <li>otherwise, deny or decline access</li>
229 <p>Other <directive module="core">Require</directive> values may also be
230 used which may require loading additional authorization modules.</p>
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>
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>
247 <p><module>mod_authnz_ldap</module> uses the following directives during the
251 <columnspec><column width=".4"/><column width=".6"/></columnspec>
253 <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive> </td>
255 <td>The attribute specified in the
256 URL is used in compare operations for the <code>require
257 ldap-user</code> operation.</td>
262 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive></td>
264 <td>Determines the behavior of the
265 <code>require ldap-dn</code> directive.</td>
270 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive></td>
272 <td>Determines the attribute to
273 use for comparisons in the <code>require ldap-group</code>
279 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive></td>
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>
289 <section id="requiredirectives"><title>The require Directives</title>
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>
299 <section id="reqvaliduser"><title>require valid-user</title>
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
305 <directive module="mod_authnz_ldap">AuthzLDAPAuthoritative</directive>
306 directive be set to off.</p>
309 <section id="requser"><title>require ldap-user</title>
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>
327 require ldap-user "Barbara Jenson"<br />
328 require ldap-user "Fred User"<br />
329 require ldap-user "Joe Manager"<br />
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>
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>
345 <section id="reqgroup"><title>require ldap-group</title>
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>
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 />
359 <p>The following directive would grant access to both Fred and
361 <example>require ldap-group cn=Administrators, o=Airius</example>
363 <p>Behavior of this directive is modified by the <directive
364 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive> and
366 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive>
370 <section id="reqdn"><title>require ldap-dn</title>
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>
380 <p>The following directive would grant access to a specific
382 <example>require ldap-dn cn=Barbara Jenson, o=Airius</example>
384 <p>Behavior of this directive is modified by the <directive
385 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive>
389 <section id="reqattribute"><title>require ldap-attribute</title>
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>
396 <p>The following directive would grant access to anyone with
397 the attribute employeeType = active</p>
399 <example>require ldap-attribute employeeType=active</example>
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>
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>
412 <example>require ldap-attribute city="San Jose" status=active</example>
416 <section id="reqfilter"><title>require ldap-filter</title>
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>
423 <p>The following directive would grant access to anyone having a cell phone
424 and is in the marketing department</p>
426 <example>require ldap-filter &(cell=*)(department=marketing)</example>
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>
440 <section id="examples"><title>Examples</title>
444 Grant access to anyone who exists in the LDAP directory,
445 using their UID for searches.
447 AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)<br />
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 />
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>.
471 AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn<br />
477 Grant access to anybody in the Administrators group. The
478 users must authenticate using their UID.
480 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid<br />
481 require ldap-group cn=Administrators, o=Airius
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
492 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)<br />
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
508 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))<br />
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
518 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</example>
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>
524 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</example>
526 <p>The above search will succeed whether <em>jmanager</em>
527 has a pager or not.</p>
532 <section id="usingtls"><title>Using TLS</title>
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>
539 <section id="usingssl"><title>Using SSL</title>
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>
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>
550 <section id="frontpage"><title>Using Microsoft
551 FrontPage with mod_authnz_ldap</title>
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>
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>
567 AuthLDAPURL "the url"
568 AuthzLDAPAuthoritative off
569 AuthGroupFile <em>mygroupfile</em>
570 require group <em>mygroupfile</em>
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>
579 <section id="howitworks"><title>How It Works</title>
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>
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>
597 <section id="fpcaveats"><title>Caveats</title>
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>
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>
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>
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>
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>
646 <override>AuthConfig</override>
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>
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>
663 <override>AuthConfig</override>
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>
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>
678 <override>AuthConfig</override>
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>
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>
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>
705 <p>The file contains lines in the following format:</p>
708 <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
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>
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>
723 <override>AuthConfig</override>
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>
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>
747 <override>AuthConfig</override>
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>
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>
762 <override>AuthConfig</override>
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>
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>
781 <override>AuthConfig</override>
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>
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>
805 <override>AuthConfig</override>
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
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>
822 <override>AuthConfig</override>
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>
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>
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>
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
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>
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>
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>
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>
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>
896 <p>When doing searches, the attribute, filter and username passed
897 by the HTTP client are combined to create a search filter that
899 <code>(&(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
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>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
907 <p>See above for examples of <directive
908 module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>