2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
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>
99 <li><a href="#activedirectory">Using Active Directory</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
230 be used which may require loading additional authorization modules.
231 Note that if you use a <directive module="core">Require</directive>
232 value from another authorization module, you will need to ensure that
233 <directive module="mod_authnz_ldap">AuthzLDAPAuthoritative</directive>
234 is set to <code>off</code> to allow the authorization phase to fall
235 back to the module providing the alternate
236 <directive module="core">Require</directive> value.</p>
239 <li>Grant access if there is a <a href="#requser"><code>Require
240 valid-user</code></a> directive. (requires
241 <module>mod_authz_user</module>)</li>
243 <li>Grant access if there is a <a
244 href="#reqgroup"><code>Require group</code></a> directive, and
245 <module>mod_authz_groupfile</module> has been loaded with the
246 <directive module="mod_authz_groupfile">AuthGroupFile</directive>
253 <p><module>mod_authnz_ldap</module> uses the following directives during the
257 <columnspec><column width=".4"/><column width=".6"/></columnspec>
259 <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive> </td>
261 <td>The attribute specified in the
262 URL is used in compare operations for the <code>Require
263 ldap-user</code> operation.</td>
268 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive></td>
270 <td>Determines the behavior of the
271 <code>Require ldap-dn</code> directive.</td>
276 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive></td>
278 <td>Determines the attribute to
279 use for comparisons in the <code>Require ldap-group</code>
285 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive></td>
287 <td>Specifies whether to use the
288 user DN or the username when doing comparisons for the
289 <code>Require ldap-group</code> directive.</td>
295 <section id="requiredirectives"><title>The Require Directives</title>
297 <p>Apache's <directive module="core">Require</directive>
298 directives are used during the authorization phase to ensure that
299 a user is allowed to access a resource. mod_authnz_ldap extends the
300 authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
301 <code>ldap-group</code>, <code>ldap-attribute</code> and
302 <code>ldap-filter</code>. Other authorization types may also be
303 used but may require that additional authorization modules be loaded.</p>
305 <section id="reqvaliduser"><title>Require valid-user</title>
307 <p>If this directive exists, <module>mod_authnz_ldap</module> grants
308 access to any user that has successfully authenticated during the
309 search/bind phase. Requires that <module>mod_authz_user</module> be
313 <section id="requser"><title>Require ldap-user</title>
315 <p>The <code>Require ldap-user</code> directive specifies what
316 usernames can access the resource. Once
317 <module>mod_authnz_ldap</module> has retrieved a unique DN from the
318 directory, it does an LDAP compare operation using the username
319 specified in the <code>Require ldap-user</code> to see if that username
320 is part of the just-fetched LDAP entry. Multiple users can be
321 granted access by putting multiple usernames on the line,
322 separated with spaces. If a username has a space in it, then it
323 must be surrounded with double quotes. Multiple users can also be
324 granted access by using multiple <code>Require ldap-user</code>
325 directives, with one user per line. For example, with a <directive
326 module="mod_authnz_ldap">AuthLDAPURL</directive> of
327 <code>ldap://ldap/o=Airius?cn</code> (i.e., <code>cn</code> is
328 used for searches), the following Require directives could be used
329 to restrict access:</p>
331 Require ldap-user "Barbara Jenson"<br />
332 Require ldap-user "Fred User"<br />
333 Require ldap-user "Joe Manager"<br />
336 <p>Because of the way that <module>mod_authnz_ldap</module> handles this
337 directive, Barbara Jenson could sign on as <em>Barbara
338 Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
339 she has in her LDAP entry. Only the single <code>Require
340 ldap-user</code> line is needed to support all values of the attribute
341 in the user's entry.</p>
343 <p>If the <code>uid</code> attribute was used instead of the
344 <code>cn</code> attribute in the URL above, the above three lines
345 could be condensed to</p>
346 <example>Require ldap-user bjenson fuser jmanager</example>
349 <section id="reqgroup"><title>Require ldap-group</title>
351 <p>This directive specifies an LDAP group whose members are
352 allowed access. It takes the distinguished name of the LDAP
353 group. Note: Do not surround the group name with quotes.
354 For example, assume that the following entry existed in
355 the LDAP directory:</p>
357 dn: cn=Administrators, o=Airius<br />
358 objectClass: groupOfUniqueNames<br />
359 uniqueMember: cn=Barbara Jenson, o=Airius<br />
360 uniqueMember: cn=Fred User, o=Airius<br />
363 <p>The following directive would grant access to both Fred and
365 <example>Require ldap-group cn=Administrators, o=Airius</example>
367 <p>Behavior of this directive is modified by the <directive
368 module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive> and
370 module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive>
374 <section id="reqdn"><title>Require ldap-dn</title>
376 <p>The <code>Require ldap-dn</code> directive allows the administrator
377 to grant access based on distinguished names. It specifies a DN
378 that must match for access to be granted. If the distinguished
379 name that was retrieved from the directory server matches the
380 distinguished name in the <code>Require ldap-dn</code>, then
381 authorization is granted. Note: do not surround the distinguished
382 name with quotes.</p>
384 <p>The following directive would grant access to a specific
386 <example>Require ldap-dn cn=Barbara Jenson, o=Airius</example>
388 <p>Behavior of this directive is modified by the <directive
389 module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive>
393 <section id="reqattribute"><title>Require ldap-attribute</title>
395 <p>The <code>Require ldap-attribute</code> directive allows the
396 administrator to grant access based on attributes of the authenticated
397 user in the LDAP directory. If the attribute in the directory
398 matches the value given in the configuration, access is granted.</p>
400 <p>The following directive would grant access to anyone with
401 the attribute employeeType = active</p>
403 <example>Require ldap-attribute employeeType=active</example>
405 <p>Multiple attribute/value pairs can be specified on the same line
406 separated by spaces or they can be specified in multiple
407 <code>Require ldap-attribute</code> directives. The effect of listing
408 multiple attribute/values pairs is an OR operation. Access will be
409 granted if any of the listed attribute values match the value of the
410 corresponding attribute in the user object. If the value of the
411 attribute contains a space, only the value must be within double quotes.</p>
413 <p>The following directive would grant access to anyone with
414 the city attribute equal to "San Jose" or status equal to "Active"</p>
416 <example>Require ldap-attribute city="San Jose" status=active</example>
420 <section id="reqfilter"><title>Require ldap-filter</title>
422 <p>The <code>Require ldap-filter</code> directive allows the
423 administrator to grant access based on a complex LDAP search filter.
424 If the dn returned by the filter search matches the authenticated user
425 dn, access is granted.</p>
427 <p>The following directive would grant access to anyone having a cell phone
428 and is in the marketing department</p>
430 <example>Require ldap-filter &(cell=*)(department=marketing)</example>
432 <p>The difference between the <code>Require ldap-filter</code> directive and the
433 <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
434 performs a search operation on the LDAP directory using the specified search
435 filter rather than a simple attribute comparison. If a simple attribute
436 comparison is all that is required, the comparison operation performed by
437 <code>ldap-attribute</code> will be faster than the search operation
438 used by <code>ldap-filter</code> especially within a large directory.</p>
444 <section id="examples"><title>Examples</title>
448 Grant access to anyone who exists in the LDAP directory,
449 using their UID for searches.
451 AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)<br />
457 The next example is the same as above; but with the fields
458 that have useful defaults omitted. Also, note the use of a
459 redundant LDAP server.
460 <example>AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius<br />
466 The next example is similar to the previous one, but it
467 uses the common name instead of the UID. Note that this
468 could be problematical if multiple people in the directory
469 share the same <code>cn</code>, because a search on <code>cn</code>
470 <strong>must</strong> return exactly one entry. That's why
471 this approach is not recommended: it's a better idea to
472 choose an attribute that is guaranteed unique in your
473 directory, such as <code>uid</code>.
475 AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn<br />
481 Grant access to anybody in the Administrators group. The
482 users must authenticate using their UID.
484 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid<br />
485 Require ldap-group cn=Administrators, o=Airius
490 The next example assumes that everyone at Airius who
491 carries an alphanumeric pager will have an LDAP attribute
492 of <code>qpagePagerID</code>. The example will grant access
493 only to people (authenticated via their UID) who have
496 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)<br />
502 <p>The next example demonstrates the power of using filters
503 to accomplish complicated administrative requirements.
504 Without filters, it would have been necessary to create a
505 new LDAP group and ensure that the group's members remain
506 synchronized with the pager users. This becomes trivial
507 with filters. The goal is to grant access to anyone who has
508 a pager, plus grant access to Joe Manager, who doesn't
509 have a pager, but does need to access the same
512 AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))<br />
516 <p>This last may look confusing at first, so it helps to
517 evaluate what the search filter will look like based on who
518 connects, as shown below. If
519 Fred User connects as <code>fuser</code>, the filter would look
522 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</example>
524 <p>The above search will only succeed if <em>fuser</em> has a
525 pager. When Joe Manager connects as <em>jmanager</em>, the
526 filter looks like</p>
528 <example>(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</example>
530 <p>The above search will succeed whether <em>jmanager</em>
531 has a pager or not.</p>
536 <section id="usingtls"><title>Using TLS</title>
538 <p>To use TLS, see the <module>mod_ldap</module> directives <directive
539 module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
540 module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
541 module="mod_ldap">LDAPTrustedMode</directive>.</p>
543 <p>An optional second parameter can be added to the
544 <directive module="mod_authnz_ldap">AuthLDAPURL</directive> to override
545 the default connection type set by <directive module="mod_ldap">LDAPTrustedMode</directive>.
546 This will allow the connection established by an <em>ldap://</em> Url
547 to be upgraded to a secure connection on the same port.</p>
550 <section id="usingssl"><title>Using SSL</title>
552 <p>To use SSL, see the <module>mod_ldap</module> directives <directive
553 module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
554 module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
555 module="mod_ldap">LDAPTrustedMode</directive>.</p>
557 <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
558 <directive module="mod_authnz_ldap">AuthLDAPURL</directive>
559 directive, instead of <em>ldap://</em>.</p>
562 <section id="activedirectory"><title>Using Active Directory</title>
564 <p>An Active Directory installation may support multiple domains at the
565 same time. To distinguish users between domains, an identifier called
566 a User Principle Name (UPN) can be added to a user's entry in the
567 directory. This UPN usually takes the form of the user's account
568 name, followed by the domain components of the particular domain,
569 for example <em>somebody@nz.somedomain.com</em>.</p>
571 <p>You may wish to configure the <module>mod_authnz_ldap</module>
572 module to authenticate users present in any of the domains making up
573 the Active Directory forest. In this way both
574 <em>somebody@nz.somedomain.com</em> and <em>someone@au.somedomain.com</em>
575 can be authenticated using the same query at the same time.</p>
577 <p>To make this practical, Active Directory supports the concept of
578 a Global Catalog. This Global Catalog is a read only copy of selected
579 attributes of all the Active Directory servers within the Active
580 Directory forest. Querying the Global Catalog allows all the domains
581 to be queried in a single query, without the query spanning servers
582 over potentially slow links.</p>
584 <p>If enabled, the Global Catalog is an independent directory server
585 that runs on port 3268 (3269 for SSL). To search for a user, do a
586 subtree search for the attribute <em>userPrincipalName</em>, with
587 an empty search root, like so:</p>
590 AuthLDAPBindDN <em>apache@somedomain.com</em>
591 AuthLDAPBindPassword <em>password</em>
592 AuthLDAPURL <em>ldap://10.0.0.1:3268/>userPrincipalName?sub</em>
595 <p>Users will need to enter their User Principal Name as a login, in
596 the form <em>somebody@nz.somedomain.com</em>.</p>
600 <section id="frontpage"><title>Using Microsoft
601 FrontPage with mod_authnz_ldap</title>
603 <p>Normally, FrontPage uses FrontPage-web-specific user/group
604 files (i.e., the <module>mod_authn_file</module> and
605 <module>mod_authz_groupfile</module> modules) to handle all
606 authentication. Unfortunately, it is not possible to just
607 change to LDAP authentication by adding the proper directives,
608 because it will break the <em>Permissions</em> forms in
609 the FrontPage client, which attempt to modify the standard
610 text-based authorization files.</p>
612 <p>Once a FrontPage web has been created, adding LDAP
613 authentication to it is a matter of adding the following
614 directives to <em>every</em> <code>.htaccess</code> file
615 that gets created in the web</p>
617 AuthLDAPURL "the url"
618 AuthGroupFile <em>mygroupfile</em>
619 Require group <em>mygroupfile</em>
622 <section id="howitworks"><title>How It Works</title>
624 <p>FrontPage restricts access to a web by adding the <code>Require
625 valid-user</code> directive to the <code>.htaccess</code>
626 files. The <code>Require valid-user</code> directive will succeed for
627 any user who is valid <em>as far as LDAP is
628 concerned</em>. This means that anybody who has an entry in
629 the LDAP directory is considered a valid user, whereas FrontPage
630 considers only those people in the local user file to be
631 valid. By substituting the ldap-group with group file authorization,
632 Apache is allowed to consult the local user file (which is managed by
633 FrontPage) - instead of LDAP - when handling authorizing the user.</p>
635 <p>Once directives have been added as specified above,
636 FrontPage users will be able to perform all management
637 operations from the FrontPage client.</p>
640 <section id="fpcaveats"><title>Caveats</title>
643 <li>When choosing the LDAP URL, the attribute to use for
644 authentication should be something that will also be valid
645 for putting into a <module>mod_authn_file</module> user file.
646 The user ID is ideal for this.</li>
648 <li>When adding users via FrontPage, FrontPage administrators
649 should choose usernames that already exist in the LDAP
650 directory (for obvious reasons). Also, the password that the
651 administrator enters into the form is ignored, since Apache
652 will actually be authenticating against the password in the
653 LDAP database, and not against the password in the local user
654 file. This could cause confusion for web administrators.</li>
656 <!-- XXX is that true? was mod_auth before the aaa change -->
657 <li>Apache must be compiled with <module>mod_auth_basic</module>,
658 <module>mod_authn_file</module> and
659 <module>mod_authz_groupfile</module> in order to
660 use FrontPage support. This is because Apache will still use
661 the <module>mod_authz_groupfile</module> group file for determine
662 the extent of a user's access to the FrontPage web.</li>
664 <li>The directives must be put in the <code>.htaccess</code>
665 files. Attempting to put them inside <directive module="core"
666 type="section">Location</directive> or <directive module="core"
667 type="section">Directory</directive> directives won't work. This
668 is because <module>mod_authnz_ldap</module> has to be able to grab
669 the <directive module="mod_authn_file">AuthGroupFile</directive>
670 directive that is found in FrontPage <code>.htaccess</code>
671 files so that it knows where to look for the valid user list. If
672 the <module>mod_authnz_ldap</module> directives aren't in the same
673 <code>.htaccess</code> file as the FrontPage directives, then
674 the hack won't work, because <module>mod_authnz_ldap</module> will
675 never get a chance to process the <code>.htaccess</code> file,
676 and won't be able to find the FrontPage-managed user file.</li>
682 <name>AuthLDAPBindDN</name>
683 <description>Optional DN to use in binding to the LDAP server</description>
684 <syntax>AuthLDAPBindDN <em>distinguished-name</em></syntax>
685 <contextlist><context>directory</context><context>.htaccess</context>
687 <override>AuthConfig</override>
690 <p>An optional DN used to bind to the server when searching for
691 entries. If not provided, <module>mod_authnz_ldap</module> will use
692 an anonymous bind.</p>
697 <name>AuthLDAPBindPassword</name>
698 <description>Password used in conjuction with the bind DN</description>
699 <syntax>AuthLDAPBindPassword <em>password</em></syntax>
700 <contextlist><context>directory</context><context>.htaccess</context>
702 <override>AuthConfig</override>
705 <p>A bind password to use in conjunction with the bind DN. Note
706 that the bind password is probably sensitive data, and should be
707 properly protected. You should only use the <directive
708 module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
709 module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
710 absolutely need them to search the directory.</p>
715 <name>AuthLDAPCharsetConfig</name>
716 <description>Language to charset conversion configuration file</description>
717 <syntax>AuthLDAPCharsetConfig <em>file-path</em></syntax>
718 <contextlist><context>server config</context>
722 <p>The <directive>AuthLDAPCharsetConfig</directive> directive sets the location
723 of the language to charset conversion configuration file. <var>File-path</var> is relative
724 to the <directive module="core">ServerRoot</directive>. This file specifies
725 the list of language extensions to character sets.
726 Most administrators use the provided <code>charset.conv</code>
727 file, which associates common language extensions to character sets.</p>
729 <p>The file contains lines in the following format:</p>
732 <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
735 <p>The case of the extension does not matter. Blank lines, and lines
736 beginning with a hash character (<code>#</code>) are ignored.</p>
741 <name>AuthLDAPCompareDNOnServer</name>
742 <description>Use the LDAP server to compare the DNs</description>
743 <syntax>AuthLDAPCompareDNOnServer on|off</syntax>
744 <default>AuthLDAPCompareDNOnServer on</default>
745 <contextlist><context>directory</context><context>.htaccess</context>
747 <override>AuthConfig</override>
750 <p>When set, <module>mod_authnz_ldap</module> will use the LDAP
751 server to compare the DNs. This is the only foolproof way to
752 compare DNs. <module>mod_authnz_ldap</module> will search the
753 directory for the DN specified with the <a
754 href="#reqdn"><code>Require dn</code></a> directive, then,
755 retrieve the DN and compare it with the DN retrieved from the user
756 entry. If this directive is not set,
757 <module>mod_authnz_ldap</module> simply does a string comparison. It
758 is possible to get false negatives with this approach, but it is
759 much faster. Note the <module>mod_ldap</module> cache can speed up
760 DN comparison in most situations.</p>
765 <name>AuthLDAPDereferenceAliases</name>
766 <description>When will the module de-reference aliases</description>
767 <syntax>AuthLDAPDereferenceAliases never|searching|finding|always</syntax>
768 <default>AuthLDAPDereferenceAliases always</default>
769 <contextlist><context>directory</context><context>.htaccess</context>
771 <override>AuthConfig</override>
774 <p>This directive specifies when <module>mod_authnz_ldap</module> will
775 de-reference aliases during LDAP operations. The default is
776 <code>always</code>.</p>
781 <name>AuthLDAPGroupAttribute</name>
782 <description>LDAP attributes used to check for group membership</description>
783 <syntax>AuthLDAPGroupAttribute <em>attribute</em></syntax>
784 <contextlist><context>directory</context><context>.htaccess</context>
786 <override>AuthConfig</override>
789 <p>This directive specifies which LDAP attributes are used to
790 check for group membership. Multiple attributes can be used by
791 specifying this directive multiple times. If not specified,
792 then <module>mod_authnz_ldap</module> uses the <code>member</code> and
793 <code>uniquemember</code> attributes.</p>
798 <name>AuthLDAPGroupAttributeIsDN</name>
799 <description>Use the DN of the client username when checking for
800 group membership</description>
801 <syntax>AuthLDAPGroupAttributeIsDN on|off</syntax>
802 <default>AuthLDAPGroupAttributeIsDN on</default>
803 <contextlist><context>directory</context><context>.htaccess</context>
805 <override>AuthConfig</override>
808 <p>When set <code>on</code>, this directive says to use the
809 distinguished name of the client username when checking for group
810 membership. Otherwise, the username will be used. For example,
811 assume that the client sent the username <code>bjenson</code>,
812 which corresponds to the LDAP DN <code>cn=Babs Jenson,
813 o=Airius</code>. If this directive is set,
814 <module>mod_authnz_ldap</module> will check if the group has
815 <code>cn=Babs Jenson, o=Airius</code> as a member. If this
816 directive is not set, then <module>mod_authnz_ldap</module> will
817 check if the group has <code>bjenson</code> as a member.</p>
822 <name>AuthLDAPRemoteUserAttribute</name>
823 <description>Use the value of the attribute returned during the user
824 query to set the REMOTE_USER environment variable</description>
825 <syntax>AuthLDAPRemoteUserAttribute uid</syntax>
826 <default>none</default>
827 <contextlist><context>directory</context><context>.htaccess</context>
829 <override>AuthConfig</override>
832 <p>If this directive is set, the value of the
833 <code>REMOTE_USER</code> environment variable will be set to the
834 value of the attribute specified. Make sure that this attribute is
835 included in the list of attributes in the AuthLDAPUrl definition,
836 otherwise this directive will have no effect. This directive, if
837 present, takes precedence over AuthLDAPRemoteUserIsDN. This
838 directive is useful should you want people to log into a website
839 using an email address, but a backend application expects the
840 username as a userid.</p>
845 <name>AuthLDAPRemoteUserIsDN</name>
846 <description>Use the DN of the client username to set the REMOTE_USER
847 environment variable</description>
848 <syntax>AuthLDAPRemoteUserIsDN on|off</syntax>
849 <default>AuthLDAPRemoteUserIsDN off</default>
850 <contextlist><context>directory</context><context>.htaccess</context>
852 <override>AuthConfig</override>
855 <p>If this directive is set to on, the value of the
856 <code>REMOTE_USER</code> environment variable will be set to the full
857 distinguished name of the authenticated user, rather than just
858 the username that was passed by the client. It is turned off by
864 <name>AuthLDAPUrl</name>
865 <description>URL specifying the LDAP search parameters</description>
866 <syntax>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></syntax>
867 <contextlist><context>directory</context><context>.htaccess</context>
869 <override>AuthConfig</override>
872 <p>An RFC 2255 URL which specifies the LDAP search parameters
873 to use. The syntax of the URL is</p>
874 <example>ldap://host:port/basedn?attribute?scope?filter</example>
875 <p>If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:</p>
876 <example>AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com"</example>
877 <p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
878 otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
879 You can of course use search parameters on each of these.</p>
884 <dd>For regular ldap, use the
885 string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
886 instead. Secure LDAP is only available if Apache was linked
887 to an LDAP library with SSL support.</dd>
892 <p>The name/port of the ldap server (defaults to
893 <code>localhost:389</code> for <code>ldap</code>, and
894 <code>localhost:636</code> for <code>ldaps</code>). To
895 specify multiple, redundant LDAP servers, just list all
896 servers, separated by spaces. <module>mod_authnz_ldap</module>
897 will try connecting to each server in turn, until it makes a
898 successful connection.</p>
900 <p>Once a connection has been made to a server, that
901 connection remains active for the life of the
902 <program>httpd</program> process, or until the LDAP server goes
905 <p>If the LDAP server goes down and breaks an existing
906 connection, <module>mod_authnz_ldap</module> will attempt to
907 re-connect, starting with the primary server, and trying
908 each redundant server in turn. Note that this is different
909 than a true round-robin search.</p>
914 <dd>The DN of the branch of the
915 directory where all searches should start from. At the very
916 least, this must be the top of your directory tree, but
917 could also specify a subtree in the directory.</dd>
921 <dd>The attribute to search for.
922 Although RFC 2255 allows a comma-separated list of
923 attributes, only the first attribute will be used, no
924 matter how many are provided. If no attributes are
925 provided, the default is to use <code>uid</code>. It's a good
926 idea to choose an attribute that will be unique across all
927 entries in the subtree you will be using. All attributes
928 listed will be put into the environment with an AUTHENTICATE_ prefix
929 for use by other modules.</dd>
933 <dd>The scope of the search. Can be either <code>one</code> or
934 <code>sub</code>. Note that a scope of <code>base</code> is
935 also supported by RFC 2255, but is not supported by this
936 module. If the scope is not provided, or if <code>base</code> scope
937 is specified, the default is to use a scope of
938 <code>sub</code>.</dd>
942 <dd>A valid LDAP search filter. If
943 not provided, defaults to <code>(objectClass=*)</code>, which
944 will search for all objects in the tree. Filters are
945 limited to approximately 8000 characters (the definition of
946 <code>MAX_STRING_LEN</code> in the Apache source code). This
947 should be more than sufficient for any application.</dd>
950 <p>When doing searches, the attribute, filter and username passed
951 by the HTTP client are combined to create a search filter that
953 <code>(&(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
955 <p>For example, consider an URL of
956 <code>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</code>. When
957 a client attempts to connect using a username of <code>Babs
958 Jenson</code>, the resulting search filter will be
959 <code>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
961 <p>An optional parameter can be added to allow the LDAP Url to override
962 the connection type. This parameter can be one of the following:</p>
966 <dd>Establish an unsecure connection on the default LDAP port. This
967 is the same as <code>ldap://</code> on port 389.</dd>
969 <dd>Establish a secure connection on the default secure LDAP port.
970 This is the same as <code>ldaps://</code></dd>
971 <dt>TLS | STARTTLS</dt>
972 <dd>Establish an upgraded secure connection on the default LDAP port.
973 This connection will be initiated on port 389 by default and then
974 upgraded to a secure connection on the same port.</dd>
977 <p>See above for examples of <directive
978 module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>