2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $Revision: 1.1 $ -->
7 Copyright 2002-2004 The Apache Software Foundation
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
22 <modulesynopsis metafile="mod_authnz_ldap.xml.meta">
24 <name>mod_authnz_ldap</name>
25 <description>Allows an LDAP directory to be used to store the database
26 for HTTP Basic authentication.</description>
27 <status>Extension</status>
28 <sourcefile>mod_authnz_ldap.c</sourcefile>
29 <identifier>authnz_ldap_module</identifier>
30 <compatibility>Available in version 2.1 and later</compatibility>
33 <p>This module provides authentication front-ends such as
34 <module>mod_auth_basic</module> to authenticate users through
35 an ldap directory.</p>
37 <p><module>mod_authnz_ldap</module> supports the following features:</p>
40 <li>Known to support the <a
41 href="http://www.openldap.org/">OpenLDAP SDK</a> (both 1.x
42 and 2.x), <a href="http://developer.novell.com/ndk/cldap.htm">
43 Novell LDAP SDK</a> and the <a
44 href="http://www.iplanet.com/downloads/developer/">iPlanet
45 (Netscape)</a> SDK.</li>
47 <li>Complex authorization policies can be implemented by
48 representing the policy with LDAP filters.</li>
50 <li>Uses extensive caching of LDAP operations via <a
51 href="mod_ldap.html">mod_ldap</a>.</li>
53 <li>Support for LDAP over SSL (requires the Netscape SDK) or
54 TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).</li>
57 <p>When using <module>mod_auth_basic</module>, this module is invoked
58 via the <directive module="mod_auth_basic">AuthBasicProvider</directive>
59 directive with the <code>ldap</code> value.</p>
62 <seealso><module>mod_ldap</module></seealso>
63 <seealso><module>mod_auth_basic</module></seealso>
64 <seealso><module>mod_authz_user</module></seealso>
65 <seealso><module>mod_authz_groupfile</module></seealso>
67 <section id="contents"><title>Contents</title>
71 <a href="#operation">Operation</a>
74 <li><a href="#authenphase">The Authentication
77 <li><a href="#authorphase">The Authorization
83 <a href="#requiredirectives">The require Directives</a>
86 <li><a href="#reqvaliduser">require valid-user</a></li>
87 <li><a href="#requser">require ldap-user</a></li>
88 <li><a href="#reqgroup">require ldap-group</a></li>
89 <li><a href="#reqdn">require ldap-dn</a></li>
93 <li><a href="#examples">Examples</a></li>
94 <li><a href="#usingtls">Using TLS</a></li>
95 <li><a href="#usingssl">Using SSL</a></li>
98 <a href="#frontpage">Using Microsoft FrontPage with
99 <module>mod_authnz_ldap</module></a>
102 <li><a href="#howitworks">How It Works</a></li>
103 <li><a href="#fpcaveats">Caveats</a></li>
109 <section id="operation"><title>Operation</title>
111 <p>There are two phases in granting access to a user. The first
112 phase is authentication, in which the <module>mod_authnz_ldap</module>
113 authentication provider verifies that the user's credentials are valid.
114 This is also called the <em>search/bind</em> phase. The second phase is
115 authorization, in which <module>mod_authnz_ldap</module> determines
116 if the authenticated user is allowed access to the resource in
117 question. This is also known as the <em>compare</em>
120 <p><module>mod_authnz_ldap</module> registers both an authn_ldap authentication
121 provider and an anthz_ldap authorization handler. The authn_ldap
122 authentication provider can be enabled through the
123 <directive module="mod_auth_basic">AuthBasicProvider</directive> directive
124 using the <code>ldap</code> value. The authz_ldap handler extends the
125 <directive module="core">Require</directive> directive's authorization types
126 by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
129 <section id="authenphase"><title>The Authentication
132 <p>During the authentication phase, <module>mod_authnz_ldap</module>
133 searches for an entry in the directory that matches the username
134 that the HTTP client passes. If a single unique match is found,
135 then <module>mod_authnz_ldap</module> attempts to bind to the
136 directory server using the DN of the entry plus the password
137 provided by the HTTP client. Because it does a search, then a
138 bind, it is often referred to as the search/bind phase. Here are
139 the steps taken during the search/bind phase.</p>
142 <li>Generate a search filter by combining the attribute and
143 filter provided in the <directive module="mod_authnz_ldap"
144 >AuthLDAPURL</directive> directive with
145 the username passed by the HTTP client.</li>
147 <li>Search the directory using the generated filter. If the
148 search does not return exactly one entry, deny or decline
151 <li>Fetch the distinguished name of the entry retrieved from
152 the search and attempt to bind to the LDAP server using the
153 DN and the password passed by the HTTP client. If the bind is
154 unsuccessful, deny or decline access.</li>
157 <p>The following directives are used during the search/bind
161 <columnspec><column width=".3"/><column width=".7"/></columnspec>
163 <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive></td>
165 <td>Specifies the LDAP server, the
166 base DN, the attribute to use in the search, as well as the
167 extra search filter to use.</td>
171 <td><directive module="mod_authnz_ldap">AuthLDAPBindDN</directive></td>
173 <td>An optional DN to bind with
174 during the search phase.</td>
179 module="mod_authnz_ldap">AuthLDAPBindPassword</directive></td>
181 <td>An optional password to bind
182 with during the search phase.</td>
187 <section id="authorphase"><title>The Authorization Phase</title>
189 <p>During the authorization phase, <module>mod_authnz_ldap</module>
190 attempts to determine if the user is authorized to access the
191 resource. Many of these checks require
192 <module>mod_authnz_ldap</module> to do a compare operation on the
193 LDAP server. This is why this phase is often referred to as the
194 compare phase. <module>mod_authnz_ldap</module> accepts the
195 following <directive module="core">Require</directive>
196 directives to determine if the credentials are acceptable:</p>
199 <li>Grant access if there is a <a
200 href="#reqgroup"><code>require ldap-user</code></a> directive, and the
201 username in the directive matches the username passed by the
204 <li>Grant access if there is a <a href="#reqdn"><code>require
205 ldap-dn</code></a> directive, and the DN in the directive matches
206 the DN fetched from the LDAP directory.</li>
208 <li>Grant access if there is a <a
209 href="#reqgroup"><code>require ldap-group</code></a> directive, and
210 the DN fetched from the LDAP directory (or the username
211 passed by the client) occurs in the LDAP group.</li>
213 <li>otherwise, deny or decline access</li>
216 <p>Other <directive module="core">Require</directive> values may also be
217 used which may require loading additional authorization modules.</p>
220 <li>Grant access if there is a <a href="#requser"><code>require
221 valid-user</code></a> directive. (requires
222 <module>mod_authz_user</module>)</li>
224 <li>Grant access if there is a <a
225 href="#reqgroup"><code>require group</code></a> directive, and
226 <module>mod_authz_groupfile</module> has been loaded with the
227 <directive module="mod_authz_groupfile">AuthGroupFile</directive>
234 <p><module>mod_authnz_ldap</module> uses the following directives during the
238 <columnspec><column width=".4"/><column width=".6"/></columnspec>
240 <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive> </td>
242 <td>The attribute specified in the
243 URL is used in compare operations for the <code>require
244 user</code> operation.</td>
249 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive></td>
251 <td>Determines the behavior of the
252 <code>require dn</code> directive.</td>
257 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive></td>
259 <td>Determines the attribute to
260 use for comparisons in the <code>require group</code>
266 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive></td>
268 <td>Specifies whether to use the
269 user DN or the username when doing comparisons for the
270 <code>require group</code> directive.</td>
276 <section id="requiredirectives"><title>The require Directives</title>
278 <p>Apache's <directive module="core">Require</directive>
279 directives are used during the authorization phase to ensure that
280 a user is allowed to access a resource. mod_authnz_ldap extends the
281 authorization types with <code>ldap-user</code>, <code>ldap-dn</code>
282 and <code>ldap-group</code>. Other authorization types may also be
283 used but may require that additional authorization modules be loaded.</p>
285 <section id="reqvaliduser"><title>require valid-user</title>
287 <p>If this directive exists, <module>mod_authnz_ldap</module> grants
288 access to any user that has successfully authenticated during the
289 search/bind phase. Requires that <module>mod_authz_user</module> be
291 <directive module="mod_authnz_ldap">AuthLDAPAuthoritative</directive>
292 directive be set to off.</p>
295 <section id="requser"><title>require ldap-user</title>
297 <p>The <code>require ldap-user</code> directive specifies what
298 usernames can access the resource. Once
299 <module>mod_authnz_ldap</module> has retrieved a unique DN from the
300 directory, it does an LDAP compare operation using the username
301 specified in the <code>require ldap-user</code> to see if that username
302 is part of the just-fetched LDAP entry. Multiple users can be
303 granted access by putting multiple usernames on the line,
304 separated with spaces. If a username has a space in it, then it
305 must be surrounded with double quotes. Multiple users can also be
306 granted access by using multiple <code>require ldap-user</code>
307 directives, with one user per line. For example, with a <directive
308 module="mod_authnz_ldap">AuthLDAPURL</directive> of
309 <code>ldap://ldap/o=Airius?cn</code> (i.e., <code>cn</code> is
310 used for searches), the following require directives could be used
311 to restrict access:</p>
313 require ldap-user "Barbara Jenson"<br />
314 require ldap-user "Fred User"<br />
315 require ldap-user "Joe Manager"<br />
318 <p>Because of the way that <module>mod_authnz_ldap</module> handles this
319 directive, Barbara Jenson could sign on as <em>Barbara
320 Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
321 she has in her LDAP entry. Only the single <code>require
322 ldap-user</code> line is needed to support all values of the attribute
323 in the user's entry.</p>
325 <p>If the <code>uid</code> attribute was used instead of the
326 <code>cn</code> attribute in the URL above, the above three lines
327 could be condensed to</p>
328 <example>require ldap-user bjenson fuser jmanager</example>
331 <section id="reqgroup"><title>require ldap-group</title>
333 <p>This directive specifies an LDAP group whose members are
334 allowed access. It takes the distinguished name of the LDAP
335 group. Note: Do not surround the group name with quotes.
336 For example, assume that the following entry existed in
337 the LDAP directory:</p>
339 dn: cn=Administrators, o=Airius<br />
340 objectClass: groupOfUniqueNames<br />
341 uniqueMember: cn=Barbara Jenson, o=Airius<br />
342 uniqueMember: cn=Fred User, o=Airius<br />
345 <p>The following directive would grant access to both Fred and
347 <example>require ldap-group cn=Administrators, o=Airius</example>
349 <p>Behavior of this directive is modified by the <directive
350 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive> and
352 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive>
356 <section id="reqdn"><title>require ldap-dn</title>
358 <p>The <code>require ldap-dn</code> directive allows the administrator
359 to grant access based on distinguished names. It specifies a DN
360 that must match for access to be granted. If the distinguished
361 name that was retrieved from the directory server matches the
362 distinguished name in the <code>require ldap-dn</code>, then
363 authorization is granted. Note: do not surround the distinguished
364 name with quotes.</p>
366 <p>The following directive would grant access to a specific
368 <example>require ldap-dn cn=Barbara Jenson, o=Airius</example>
370 <p>Behavior of this directive is modified by the <directive
371 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive>
376 <section id="examples"><title>Examples</title>
380 Grant access to anyone who exists in the LDAP directory,
381 using their UID for searches.
383 AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)<br />
389 The next example is the same as above; but with the fields
390 that have useful defaults omitted. Also, note the use of a
391 redundant LDAP server.
392 <example>AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius<br />
398 The next example is similar to the previous one, but is
399 uses the common name instead of the UID. Note that this
400 could be problematical if multiple people in the directory
401 share the same <code>cn</code>, because a search on <code>cn</code>
402 <strong>must</strong> return exactly one entry. That's why
403 this approach is not recommended: it's a better idea to
404 choose an attribute that is guaranteed unique in your
405 directory, such as <code>uid</code>.
407 AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn<br />
413 Grant access to anybody in the Administrators group. The
414 users must authenticate using their UID.
416 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid<br />
417 require ldap-group cn=Administrators, o=Airius
422 The next example assumes that everyone at Airius who
423 carries an alphanumeric pager will have an LDAP attribute
424 of <code>qpagePagerID</code>. The example will grant access
425 only to people (authenticated via their UID) who have
428 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)<br />
434 <p>The next example demonstrates the power of using filters
435 to accomplish complicated administrative requirements.
436 Without filters, it would have been necessary to create a
437 new LDAP group and ensure that the group's members remain
438 synchronized with the pager users. This becomes trivial
439 with filters. The goal is to grant access to anyone who has
440 a filter, plus grant access to Joe Manager, who doesn't
441 have a pager, but does need to access the same
444 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))<br />
448 <p>This last may look confusing at first, so it helps to
449 evaluate what the search filter will look like based on who
450 connects, as shown below. The text in blue is the part that
451 is filled in using the attribute specified in the URL. The
452 text in red is the part that is filled in using the filter
453 specified in the URL. The text in green is filled in using
454 the information that is retrieved from the HTTP client. If
455 Fred User connects as <code>fuser</code>, the filter would look
458 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</example>
460 <p>The above search will only succeed if <em>fuser</em> has a
461 pager. When Joe Manager connects as <em>jmanager</em>, the
462 filter looks like</p>
464 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</example>
466 <p>The above search will succeed whether <em>jmanager</em>
467 has a pager or not.</p>
472 <section id="usingtls"><title>Using TLS</title>
474 <p>To use TLS, see the <module>mod_ldap</module> directives <directive
475 module="mod_ldap">LDAPTrustedCA</directive> and <directive
476 module="mod_ldap">LDAPTrustedCAType</directive>.</p>
479 <section id="usingssl"><title>Using SSL</title>
481 <p>To use SSL, see the <module>mod_ldap</module> directives <directive
482 module="mod_ldap">LDAPTrustedCA</directive> and <directive
483 module="mod_ldap">LDAPTrustedCAType</directive>.</p>
485 <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
486 <directive module="mod_authnz_ldap">AuthLDAPURL</directive>
487 directive, instead of <em>ldap://</em>.</p>
490 <section id="frontpage"><title>Using Microsoft
491 FrontPage with mod_authnz_ldap</title>
493 <p>Normally, FrontPage uses FrontPage-web-specific user/group
494 files (i.e., the <module>mod_authn_file</module> and
495 <module>mod_authz_groupfile</module> modules) to handle all
496 authentication. Unfortunately, it is not possible to just
497 change to LDAP authentication by adding the proper directives,
498 because it will break the <em>Permissions</em> forms in
499 the FrontPage client, which attempt to modify the standard
500 text-based authorization files.</p>
502 <p>Once a FrontPage web has been created, adding LDAP
503 authentication to it is a matter of adding the following
504 directives to <em>every</em> <code>.htaccess</code> file
505 that gets created in the web</p>
507 AuthLDAPURL "the url"
508 AuthLDAPAuthoritative off
509 AuthGroupFile <em>mygroupfile</em>
510 require group <em>mygroupfile</em>
513 <p><directive module="mod_authnz_ldap">AuthLDAPAuthoritative</directive>
514 must be off to allow <module>mod_authnz_ldap</module> to decline group
515 authentication so that Apache will fall back to file
516 authentication for checking group membership. This allows the
517 FrontPage-managed group file to be used.</p>
519 <section id="howitworks"><title>How It Works</title>
521 <p>FrontPage restricts access to a web by adding the <code>require
522 valid-user</code> directive to the <code>.htaccess</code>
523 files. The <code>require valid-user</code> directive will succeed for
524 any user who is valid <em>as far as LDAP is
525 concerned</em>. This means that anybody who has an entry in
526 the LDAP directory is considered a valid user, whereas FrontPage
527 considers only those people in the local user file to be
528 valid. By substituting the ldap-group with group file authorization,
529 Apache is allowed to consult the local user file (which is managed by
530 FrontPage) - instead of LDAP - when handling authorizing the user.</p>
532 <p>Once directives have been added as specified above,
533 FrontPage users will be able to perform all management
534 operations from the FrontPage client.</p>
537 <section id="fpcaveats"><title>Caveats</title>
540 <li>When choosing the LDAP URL, the attribute to use for
541 authentication should be something that will also be valid
542 for putting into a <module>mod_authn_file</module> user file.
543 The user ID is ideal for this.</li>
545 <li>When adding users via FrontPage, FrontPage administrators
546 should choose usernames that already exist in the LDAP
547 directory (for obvious reasons). Also, the password that the
548 administrator enters into the form is ignored, since Apache
549 will actually be authenticating against the password in the
550 LDAP database, and not against the password in the local user
551 file. This could cause confusion for web administrators.</li>
553 <!-- XXX is that true? was mod_auth before the aaa change -->
554 <li>Apache must be compiled with <module>mod_auth_basic</module>,
555 <module>mod_authn_file</module> and
556 <module>mod_authz_groupfile</module> in order to
557 use FrontPage support. This is because Apache will still use
558 the <module>mod_authz_groupfile</module> group file for determine
559 the extent of a user's access to the FrontPage web.</li>
561 <li>The directives must be put in the <code>.htaccess</code>
562 files. Attempting to put them inside <directive module="core"
563 type="section">Location</directive> or <directive module="core"
564 type="section">Directory</directive> directives won't work. This
565 is because <module>mod_authnz_ldap</module> has to be able to grab
566 the <directive module="mod_authn_file">AuthGroupFile</directive>
567 directive that is found in FrontPage <code>.htaccess</code>
568 files so that it knows where to look for the valid user list. If
569 the <module>mod_authnz_ldap</module> directives aren't in the same
570 <code>.htaccess</code> file as the FrontPage directives, then
571 the hack won't work, because <module>mod_authnz_ldap</module> will
572 never get a chance to process the <code>.htaccess</code> file,
573 and won't be able to find the FrontPage-managed user file.</li>
579 <name>AuthLDAPAuthoritative</name>
580 <description>Prevent other authentication modules from
581 authenticating the user if this one fails</description>
582 <syntax>AuthLDAPAuthoritative on|off</syntax>
583 <default>AuthLDAPAuthoritative on</default>
584 <contextlist><context>directory</context><context>.htaccess</context>
586 <override>AuthConfig</override>
589 <p>Set to <code>off</code> if this module should let other
590 authentication modules attempt to authenticate the user, should
591 authentication with this module fail. Control is only passed on
592 to lower modules if there is no DN or rule that matches the
593 supplied user name (as passed by the client).</p>
598 <name>AuthLDAPBindDN</name>
599 <description>Optional DN to use in binding to the LDAP server</description>
600 <syntax>AuthLDAPBindDN <em>distinguished-name</em></syntax>
601 <contextlist><context>directory</context><context>.htaccess</context>
603 <override>AuthConfig</override>
606 <p>An optional DN used to bind to the server when searching for
607 entries. If not provided, <module>mod_authnz_ldap</module> will use
608 an anonymous bind.</p>
613 <name>AuthLDAPBindPassword</name>
614 <description>Password used in conjuction with the bind DN</description>
615 <syntax>AuthLDAPBindPassword <em>password</em></syntax>
616 <contextlist><context>directory</context><context>.htaccess</context>
618 <override>AuthConfig</override>
621 <p>A bind password to use in conjunction with the bind DN. Note
622 that the bind password is probably sensitive data, and should be
623 properly protected. You should only use the <directive
624 module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
625 module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
626 absolutely need them to search the directory.</p>
631 <name>AuthLDAPCharsetConfig</name>
632 <description>Language to charset conversion configuration file</description>
633 <syntax>AuthLDAPCharsetConfig <em>file-path</em></syntax>
634 <contextlist><context>server config</context>
638 <p>The <directive>AuthLDAPCharsetConfig</directive> directive sets the location
639 of the language to charset conversion configuration file. <var>File-path</var> is relative
640 to the <directive module="core">ServerRoot</directive>. This file specifies
641 the list of language extensions to character sets.
642 Most administrators use the provided <code>charset.conv</code>
643 file, which associates common language extensions to character sets.</p>
645 <p>The file contains lines in the following format:</p>
648 <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
651 <p>The case of the extension does not matter. Blank lines, and lines
652 beginning with a hash character (<code>#</code>) are ignored.</p>
657 <name>AuthLDAPCompareDNOnServer</name>
658 <description>Use the LDAP server to compare the DNs</description>
659 <syntax>AuthLDAPCompareDNOnServer on|off</syntax>
660 <default>AuthLDAPCompareDNOnServer on</default>
661 <contextlist><context>directory</context><context>.htaccess</context>
663 <override>AuthConfig</override>
666 <p>When set, <module>mod_authnz_ldap</module> will use the LDAP
667 server to compare the DNs. This is the only foolproof way to
668 compare DNs. <module>mod_authnz_ldap</module> will search the
669 directory for the DN specified with the <a
670 href="#reqdn"><code>require dn</code></a> directive, then,
671 retrieve the DN and compare it with the DN retrieved from the user
672 entry. If this directive is not set,
673 <module>mod_authnz_ldap</module> simply does a string comparison. It
674 is possible to get false negatives with this approach, but it is
675 much faster. Note the <module>mod_ldap</module> cache can speed up
676 DN comparison in most situations.</p>
681 <name>AuthLDAPDereferenceAliases</name>
682 <description>When will the module de-reference aliases</description>
683 <syntax>AuthLDAPDereferenceAliases never|searching|finding|always</syntax>
684 <default>AuthLDAPDereferenceAliases Always</default>
685 <contextlist><context>directory</context><context>.htaccess</context>
687 <override>AuthConfig</override>
690 <p>This directive specifies when <module>mod_authnz_ldap</module> will
691 de-reference aliases during LDAP operations. The default is
692 <code>always</code>.</p>
697 <name>AuthLDAPGroupAttribute</name>
698 <description>LDAP attributes used to check for group membership</description>
699 <syntax>AuthLDAPGroupAttribute <em>attribute</em></syntax>
700 <contextlist><context>directory</context><context>.htaccess</context>
702 <override>AuthConfig</override>
705 <p>This directive specifies which LDAP attributes are used to
706 check for group membership. Multiple attributes can be used by
707 specifying this directive multiple times. If not specified,
708 then <module>mod_authnz_ldap</module> uses the <code>member</code> and
709 <code>uniquemember</code> attributes.</p>
714 <name>AuthLDAPGroupAttributeIsDN</name>
715 <description>Use the DN of the client username when checking for
716 group membership</description>
717 <syntax>AuthLDAPGroupAttributeIsDN on|off</syntax>
718 <default>AuthLDAPGroupAttributeIsDN on</default>
719 <contextlist><context>directory</context><context>.htaccess</context>
721 <override>AuthConfig</override>
724 <p>When set <code>on</code>, this directive says to use the
725 distinguished name of the client username when checking for group
726 membership. Otherwise, the username will be used. For example,
727 assume that the client sent the username <code>bjenson</code>,
728 which corresponds to the LDAP DN <code>cn=Babs Jenson,
729 o=Airius</code>. If this directive is set,
730 <module>mod_authnz_ldap</module> will check if the group has
731 <code>cn=Babs Jenson, o=Airius</code> as a member. If this
732 directive is not set, then <module>mod_authnz_ldap</module> will
733 check if the group has <code>bjenson</code> as a member.</p>
738 <name>AuthLDAPRemoteUserIsDN</name>
739 <description>Use the DN of the client username to set the REMOTE_USER
740 environment variable</description>
741 <syntax>AuthLDAPRemoteUserIsDN on|off</syntax>
742 <default>AuthLDAPRemoteUserIsDN off</default>
743 <contextlist><context>directory</context><context>.htaccess</context>
745 <override>AuthConfig</override>
748 <p>If this directive is set to on, the value of the
749 <code>REMOTE_USER</code> environment variable will be set to the full
750 distinguished name of the authenticated user, rather than just
751 the username that was passed by the client. It is turned off by
757 <name>AuthLDAPUrl</name>
758 <description>URL specifying the LDAP search parameters</description>
759 <syntax>AuthLDAPUrl <em>url</em></syntax>
760 <contextlist><context>directory</context><context>.htaccess</context>
762 <override>AuthConfig</override>
765 <p>An RFC 2255 URL which specifies the LDAP search parameters
766 to use. The syntax of the URL is</p>
767 <example>ldap://host:port/basedn?attribute?scope?filter</example>
772 <dd>For regular ldap, use the
773 string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
774 instead. Secure LDAP is only available if Apache was linked
775 to an LDAP library with SSL support.</dd>
780 <p>The name/port of the ldap server (defaults to
781 <code>localhost:389</code> for <code>ldap</code>, and
782 <code>localhost:636</code> for <code>ldaps</code>). To
783 specify multiple, redundant LDAP servers, just list all
784 servers, separated by spaces. <module>mod_authnz_ldap</module>
785 will try connecting to each server in turn, until it makes a
786 successful connection.</p>
788 <p>Once a connection has been made to a server, that
789 connection remains active for the life of the
790 <code>httpd</code> process, or until the LDAP server goes
793 <p>If the LDAP server goes down and breaks an existing
794 connection, <module>mod_authnz_ldap</module> will attempt to
795 re-connect, starting with the primary server, and trying
796 each redundant server in turn. Note that this is different
797 than a true round-robin search.</p>
802 <dd>The DN of the branch of the
803 directory where all searches should start from. At the very
804 least, this must be the top of your directory tree, but
805 could also specify a subtree in the directory.</dd>
809 <dd>The attribute to search for.
810 Although RFC 2255 allows a comma-separated list of
811 attributes, only the first attribute will be used, no
812 matter how many are provided. If no attributes are
813 provided, the default is to use <code>uid</code>. It's a good
814 idea to choose an attribute that will be unique across all
815 entries in the subtree you will be using.</dd>
819 <dd>The scope of the search. Can be either <code>one</code> or
820 <code>sub</code>. Note that a scope of <code>base</code> is
821 also supported by RFC 2255, but is not supported by this
822 module. If the scope is not provided, or if <code>base</code> scope
823 is specified, the default is to use a scope of
824 <code>sub</code>.</dd>
828 <dd>A valid LDAP search filter. If
829 not provided, defaults to <code>(objectClass=*)</code>, which
830 will search for all objects in the tree. Filters are
831 limited to approximately 8000 characters (the definition of
832 <code>MAX_STRING_LEN</code> in the Apache source code). This
833 should be than sufficient for any application.</dd>
836 <p>When doing searches, the attribute, filter and username passed
837 by the HTTP client are combined to create a search filter that
839 <code>(&(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
841 <p>For example, consider an URL of
842 <code>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</code>. When
843 a client attempts to connect using a username of <code>Babs
844 Jenson</code>, the resulting search filter will be
845 <code>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
847 <p>See above for examples of <directive
848 module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>