]> granicus.if.org Git - apache/blob - docs/manual/mod/mod_authnz_ldap.xml
Drop pre-2.3 compatibility notes from trunk docs.
[apache] / docs / manual / mod / mod_authnz_ldap.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
5
6 <!--
7  Licensed to the Apache Software Foundation (ASF) under one or more
8  contributor license agreements.  See the NOTICE file distributed with
9  this work for additional information regarding copyright ownership.
10  The ASF licenses this file to You under the Apache License, Version 2.0
11  (the "License"); you may not use this file except in compliance with
12  the License.  You may obtain a copy of the License at
13
14      http://www.apache.org/licenses/LICENSE-2.0
15
16  Unless required by applicable law or agreed to in writing, software
17  distributed under the License is distributed on an "AS IS" BASIS,
18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  See the License for the specific language governing permissions and
20  limitations under the License.
21 -->
22
23 <modulesynopsis metafile="mod_authnz_ldap.xml.meta">
24
25 <name>mod_authnz_ldap</name>
26 <description>Allows an LDAP directory to be used to store the database
27 for HTTP Basic authentication.</description>
28 <status>Extension</status>
29 <sourcefile>mod_authnz_ldap.c</sourcefile>
30 <identifier>authnz_ldap_module</identifier>
31
32 <summary>
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>
36
37     <p><module>mod_authnz_ldap</module> supports the following features:</p>
38
39     <ul>
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>
46
47       <li>Complex authorization policies can be implemented by
48       representing the policy with LDAP filters.</li>
49
50       <li>Uses extensive caching of LDAP operations via <a
51       href="mod_ldap.html">mod_ldap</a>.</li>
52
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>
55     </ul>
56
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>
60 </summary>
61
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>
66
67 <section id="contents"><title>Contents</title>
68
69     <ul>
70       <li>
71         <a href="#operation">Operation</a>
72
73         <ul>
74           <li><a href="#authenphase">The Authentication
75           Phase</a></li>
76
77           <li><a href="#authorphase">The Authorization
78           Phase</a></li>
79         </ul>
80       </li>
81
82       <li>
83         <a href="#requiredirectives">The Require Directives</a>
84
85         <ul>
86           <li><a href="#requser">Require ldap-user</a></li>
87           <li><a href="#reqgroup">Require ldap-group</a></li>
88           <li><a href="#reqdn">Require ldap-dn</a></li>
89           <li><a href="#reqattribute">Require ldap-attribute</a></li>
90           <li><a href="#reqfilter">Require ldap-filter</a></li>
91         </ul>
92       </li>
93
94       <li><a href="#examples">Examples</a></li>
95       <li><a href="#usingtls">Using TLS</a></li>
96       <li><a href="#usingssl">Using SSL</a></li>
97       <li><a href="#exposed">Exposing Login Information</a></li>
98       <li><a href="#activedirectory">Using Active Directory</a></li>
99       <li>
100         <a href="#frontpage">Using Microsoft FrontPage with
101         <module>mod_authnz_ldap</module></a>
102
103         <ul>
104           <li><a href="#howitworks">How It Works</a></li>
105           <li><a href="#fpcaveats">Caveats</a></li>
106         </ul>
107       </li>
108     </ul>
109 </section>
110
111 <section id="operation"><title>Operation</title>
112
113     <p>There are two phases in granting access to a user. The first
114     phase is authentication, in which the <module>mod_authnz_ldap</module>
115     authentication provider verifies that the user's credentials are valid.
116     This is also called the <em>search/bind</em> phase. The second phase is
117     authorization, in which <module>mod_authnz_ldap</module> determines
118     if the authenticated user is allowed access to the resource in
119     question. This is also known as the <em>compare</em>
120     phase.</p>
121
122     <p><module>mod_authnz_ldap</module> registers both an authn_ldap authentication
123     provider and an authz_ldap authorization handler.  The authn_ldap
124     authentication provider can be enabled through the
125     <directive module="mod_auth_basic">AuthBasicProvider</directive> directive
126     using the <code>ldap</code> value. The authz_ldap handler extends the
127     <directive module="mod_authz_core">Require</directive> directive's authorization types
128     by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
129     values.</p>
130
131 <section id="authenphase"><title>The Authentication
132     Phase</title>
133
134     <p>During the authentication phase, <module>mod_authnz_ldap</module>
135     searches for an entry in the directory that matches the username
136     that the HTTP client passes. If a single unique match is found,
137     then <module>mod_authnz_ldap</module> attempts to bind to the
138     directory server using the DN of the entry plus the password
139     provided by the HTTP client. Because it does a search, then a
140     bind, it is often referred to as the search/bind phase. Here are
141     the steps taken during the search/bind phase.</p>
142
143     <ol>
144       <li>Generate a search filter by combining the attribute and
145       filter provided in the <directive module="mod_authnz_ldap"
146       >AuthLDAPURL</directive> directive with
147       the username passed by the HTTP client.</li>
148
149       <li>Search the directory using the generated filter. If the
150       search does not return exactly one entry, deny or decline
151       access.</li>
152
153       <li>Fetch the distinguished name of the entry retrieved from
154       the search and attempt to bind to the LDAP server using that
155       DN and the password passed by the HTTP client. If the bind is
156       unsuccessful, deny or decline access.</li>
157     </ol>
158
159     <p>The following directives are used during the search/bind
160     phase</p>
161
162     <table>
163       <columnspec><column width=".3"/><column width=".7"/></columnspec>
164       <tr>
165         <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive></td>
166
167         <td>Specifies the LDAP server, the
168         base DN, the attribute to use in the search, as well as the
169         extra search filter to use.</td>
170       </tr>
171
172       <tr>
173         <td><directive module="mod_authnz_ldap">AuthLDAPBindDN</directive></td>
174
175         <td>An optional DN to bind with
176         during the search phase.</td>
177       </tr>
178
179       <tr>
180         <td><directive
181         module="mod_authnz_ldap">AuthLDAPBindPassword</directive></td>
182
183         <td>An optional password to bind
184         with during the search phase.</td>
185       </tr>
186     </table>
187 </section>
188
189 <section id="authorphase"><title>The Authorization Phase</title>
190
191     <p>During the authorization phase, <module>mod_authnz_ldap</module>
192     attempts to determine if the user is authorized to access the
193     resource.  Many of these checks require
194     <module>mod_authnz_ldap</module> to do a compare operation on the
195     LDAP server. This is why this phase is often referred to as the
196     compare phase. <module>mod_authnz_ldap</module> accepts the
197     following <directive module="mod_authz_core">Require</directive>
198     directives to determine if the credentials are acceptable:</p>
199
200     <ul>
201       <li>Grant access if there is a <a
202       href="#reqgroup"><code>Require ldap-user</code></a> directive, and the
203       username in the directive matches the username passed by the
204       client.</li>
205
206       <li>Grant access if there is a <a href="#reqdn"><code>Require
207       ldap-dn</code></a> directive, and the DN in the directive matches
208       the DN fetched from the LDAP directory.</li>
209
210       <li>Grant access if there is a <a
211       href="#reqgroup"><code>Require ldap-group</code></a> directive, and
212       the DN fetched from the LDAP directory (or the username
213       passed by the client) occurs in the LDAP group or, potentially, in
214       one of its sub-groups.</li>
215
216       <li>Grant access if there is a <a href="#reqattribute">
217       <code>Require ldap-attribute</code></a>
218       directive, and the attribute fetched from the LDAP directory
219       matches the given value.</li>
220
221       <li>Grant access if there is a <a href="#reqfilter">
222       <code>Require ldap-filter</code></a>
223       directive, and the search filter successfully finds a single user
224       object that matches the dn of the authenticated user.</li>
225
226       <li>otherwise, deny or decline access</li>
227     </ul>
228
229     <p>Other <directive module="mod_authz_core">Require</directive> values may also
230     be used which may require loading additional authorization modules.</p>
231
232     <ul>
233         <li>Grant access to all successfully authenticated users if
234         there is a <a href="#requser"><code>Require valid-user</code></a>
235         directive. (requires <module>mod_authz_user</module>)</li>
236
237         <li>Grant access if there is a <a
238         href="#reqgroup"><code>Require group</code></a> directive, and
239         <module>mod_authz_groupfile</module> has been loaded with the
240         <directive module="mod_authz_groupfile">AuthGroupFile</directive>
241         directive set.</li>
242
243         <li>others...</li>
244      </ul>
245
246
247     <p><module>mod_authnz_ldap</module> uses the following directives during the
248     compare phase:</p>
249
250     <table>
251       <columnspec><column width=".4"/><column width=".6"/></columnspec>
252       <tr>
253         <td><directive module="mod_authnz_ldap">AuthLDAPURL</directive> </td>
254
255         <td>The attribute specified in the
256         URL is used in compare operations for the <code>Require
257         ldap-user</code> operation.</td>
258       </tr>
259
260       <tr>
261         <td><directive
262         module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive></td>
263
264         <td>Determines the behavior of the
265         <code>Require ldap-dn</code> directive.</td>
266       </tr>
267
268       <tr>
269         <td><directive
270         module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive></td>
271
272         <td>Determines the attribute to
273         use for comparisons in the <code>Require ldap-group</code>
274         directive.</td>
275       </tr>
276
277       <tr>
278         <td><directive
279         module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive></td>
280
281         <td>Specifies whether to use the
282         user DN or the username when doing comparisons for the
283         <code>Require ldap-group</code> directive.</td>
284       </tr>
285
286       <tr>
287         <td><directive
288         module="mod_authnz_ldap">AuthLDAPMaxSubGroupDepth</directive></td>
289
290         <td>Determines the maximum depth of sub-groups that will be evaluated
291         during comparisons in the <code>Require ldap-group</code> directive.</td>
292       </tr>
293
294       <tr>
295         <td><directive
296         module="mod_authnz_ldap">AuthLDAPSubGroupAttribute</directive></td>
297
298         <td>Determines the attribute to use when obtaining sub-group members
299         of the current group during comparisons in the <code>Require ldap-group</code>
300         directive.</td>
301       </tr>
302
303       <tr>
304         <td><directive
305         module="mod_authnz_ldap">AuthLDAPSubGroupClass</directive></td>
306
307         <td>Specifies the LDAP objectClass values used to identify if queried directory
308         objects really are group objects (as opposed to user objects) during the
309         <code>Require ldap-group</code> directive's sub-group processing.</td>
310       </tr>
311     </table>
312 </section>
313 </section>
314
315 <section id="requiredirectives"><title>The Require Directives</title>
316
317     <p>Apache's <directive module="mod_authz_core">Require</directive>
318     directives are used during the authorization phase to ensure that
319     a user is allowed to access a resource.  mod_authnz_ldap extends the
320     authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
321     <code>ldap-group</code>, <code>ldap-attribute</code> and
322     <code>ldap-filter</code>.  Other authorization types may also be
323     used but may require that additional authorization modules be loaded.</p>
324
325 <section id="requser"><title>Require ldap-user</title>
326
327     <p>The <code>Require ldap-user</code> directive specifies what
328     usernames can access the resource. Once
329     <module>mod_authnz_ldap</module> has retrieved a unique DN from the
330     directory, it does an LDAP compare operation using the username
331     specified in the <code>Require ldap-user</code> to see if that username
332     is part of the just-fetched LDAP entry.  Multiple users can be
333     granted access by putting multiple usernames on the line,
334     separated with spaces. If a username has a space in it, then it
335     must be surrounded with double quotes. Multiple users can also be
336     granted access by using multiple <code>Require ldap-user</code>
337     directives, with one user per line. For example, with a <directive
338     module="mod_authnz_ldap">AuthLDAPURL</directive> of
339     <code>ldap://ldap/o=Example?cn</code> (i.e., <code>cn</code> is
340     used for searches), the following Require directives could be used
341     to restrict access:</p>
342 <highlight language="config">
343 Require ldap-user "Barbara Jenson"
344 Require ldap-user "Fred User"
345 Require ldap-user "Joe Manager"
346 </highlight>
347
348     <p>Because of the way that <module>mod_authnz_ldap</module> handles this
349     directive, Barbara Jenson could sign on as <em>Barbara
350     Jenson</em>, <em>Babs Jenson</em> or any other <code>cn</code> that
351     she has in her LDAP entry. Only the single <code>Require
352     ldap-user</code> line is needed to support all values of the attribute
353     in the user's entry.</p>
354
355     <p>If the <code>uid</code> attribute was used instead of the
356     <code>cn</code> attribute in the URL above, the above three lines
357     could be condensed to</p>
358 <highlight language="config">Require ldap-user bjenson fuser jmanager</highlight>
359 </section>
360
361 <section id="reqgroup"><title>Require ldap-group</title>
362
363     <p>This directive specifies an LDAP group whose members are
364     allowed access. It takes the distinguished name of the LDAP
365     group. Note: Do not surround the group name with quotes.
366     For example, assume that the following entry existed in
367     the LDAP directory:</p>
368 <example><pre>
369 dn: cn=Administrators, o=Example
370 objectClass: groupOfUniqueNames
371 uniqueMember: cn=Barbara Jenson, o=Example
372 uniqueMember: cn=Fred User, o=Example
373 </pre></example>
374
375     <p>The following directive would grant access to both Fred and
376     Barbara:</p>
377 <highlight language="config">Require ldap-group cn=Administrators, o=Example</highlight>
378
379     <p>Members can also be found within sub-groups of a specified LDAP group
380     if <directive module="mod_authnz_ldap">AuthLDAPMaxSubGroupDepth</directive>
381     is set to a value greater than 0. For example, assume the following entries
382     exist in the LDAP directory:</p>
383 <example><pre>
384 dn: cn=Employees, o=Example
385 objectClass: groupOfUniqueNames
386 uniqueMember: cn=Managers, o=Example
387 uniqueMember: cn=Administrators, o=Example
388 uniqueMember: cn=Users, o=Example
389
390 dn: cn=Managers, o=Example
391 objectClass: groupOfUniqueNames
392 uniqueMember: cn=Bob Ellis, o=Example
393 uniqueMember: cn=Tom Jackson, o=Example
394
395 dn: cn=Administrators, o=Example
396 objectClass: groupOfUniqueNames
397 uniqueMember: cn=Barbara Jenson, o=Example
398 uniqueMember: cn=Fred User, o=Example
399
400 dn: cn=Users, o=Example
401 objectClass: groupOfUniqueNames
402 uniqueMember: cn=Allan Jefferson, o=Example
403 uniqueMember: cn=Paul Tilley, o=Example
404 uniqueMember: cn=Temporary Employees, o=Example
405
406 dn: cn=Temporary Employees, o=Example
407 objectClass: groupOfUniqueNames
408 uniqueMember: cn=Jim Swenson, o=Example
409 uniqueMember: cn=Elliot Rhodes, o=Example
410 </pre></example>
411
412     <p>The following directives would allow access for Bob Ellis, Tom Jackson,
413     Barbara Jensen, Fred User, Allan Jefferson, and Paul Tilley but would not
414     allow access for Jim Swenson, or Elliot Rhodes (since they are at a
415     sub-group depth of 2):</p>
416 <highlight language="config">
417 Require ldap-group cn=Employees, o-Example
418 AuthLDAPMaxSubGroupDepth 1
419 </highlight>
420
421     <p>Behavior of this directive is modified by the <directive
422     module="mod_authnz_ldap">AuthLDAPGroupAttribute</directive>, <directive
423     module="mod_authnz_ldap">AuthLDAPGroupAttributeIsDN</directive>, <directive
424     module="mod_authnz_ldap">AuthLDAPMaxSubGroupDepth</directive>, <directive
425     module="mod_authnz_ldap">AuthLDAPSubGroupAttribute</directive>, and <directive
426     module="mod_authnz_ldap">AuthLDAPSubGroupClass</directive>
427     directives.</p>
428 </section>
429
430 <section id="reqdn"><title>Require ldap-dn</title>
431
432     <p>The <code>Require ldap-dn</code> directive allows the administrator
433     to grant access based on distinguished names. It specifies a DN
434     that must match for access to be granted. If the distinguished
435     name that was retrieved from the directory server matches the
436     distinguished name in the <code>Require ldap-dn</code>, then
437     authorization is granted. Note: do not surround the distinguished
438     name with quotes.</p>
439
440     <p>The following directive would grant access to a specific
441     DN:</p>
442 <highlight language="config">Require ldap-dn cn=Barbara Jenson, o=Example</highlight>
443
444     <p>Behavior of this directive is modified by the <directive
445     module="mod_authnz_ldap">AuthLDAPCompareDNOnServer</directive>
446     directive.</p>
447 </section>
448
449 <section id="reqattribute"><title>Require ldap-attribute</title>
450
451     <p>The <code>Require ldap-attribute</code> directive allows the
452     administrator to grant access based on attributes of the authenticated
453     user in the LDAP directory.  If the attribute in the directory
454     matches the value given in the configuration, access is granted.</p>
455
456     <p>The following directive would grant access to anyone with
457     the attribute employeeType = active</p>
458
459     <highlight language="config">Require ldap-attribute employeeType=active</highlight>
460
461     <p>Multiple attribute/value pairs can be specified on the same line
462     separated by spaces or they can be specified in multiple
463     <code>Require ldap-attribute</code> directives. The effect of listing
464     multiple attribute/values pairs is an OR operation. Access will be
465     granted if any of the listed attribute values match the value of the
466     corresponding attribute in the user object. If the value of the
467     attribute contains a space, only the value must be within double quotes.</p>
468
469     <p>The following directive would grant access to anyone with
470     the city attribute equal to "San Jose" or status equal to "Active"</p>
471
472     <highlight language="config">Require ldap-attribute city="San Jose" status=active</highlight>
473
474 </section>
475
476 <section id="reqfilter"><title>Require ldap-filter</title>
477
478     <p>The <code>Require ldap-filter</code> directive allows the
479     administrator to grant access based on a complex LDAP search filter.
480     If the dn returned by the filter search matches the authenticated user
481     dn, access is granted.</p>
482
483     <p>The following directive would grant access to anyone having a cell phone
484     and is in the marketing department</p>
485
486     <highlight language="config">Require ldap-filter &amp;(cell=*)(department=marketing)</highlight>
487
488     <p>The difference between the <code>Require ldap-filter</code> directive and the
489     <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
490     performs a search operation on the LDAP directory using the specified search
491     filter rather than a simple attribute comparison. If a simple attribute
492     comparison is all that is required, the comparison operation performed by
493     <code>ldap-attribute</code> will be faster than the search operation
494     used by <code>ldap-filter</code> especially within a large directory.</p>
495
496 </section>
497
498 </section>
499
500 <section id="examples"><title>Examples</title>
501
502     <ul>
503       <li>
504         Grant access to anyone who exists in the LDAP directory,
505         using their UID for searches.
506 <highlight language="config">
507 AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"
508 Require valid-user
509 </highlight>
510       </li>
511
512       <li>
513         The next example is the same as above; but with the fields
514         that have useful defaults omitted. Also, note the use of a
515         redundant LDAP server.
516 <highlight language="config">AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"
517 Require valid-user
518 </highlight>
519       </li>
520
521       <li>
522         The next example is similar to the previous one, but it
523         uses the common name instead of the UID. Note that this
524         could be problematical if multiple people in the directory
525         share the same <code>cn</code>, because a search on <code>cn</code>
526         <strong>must</strong> return exactly one entry. That's why
527         this approach is not recommended: it's a better idea to
528         choose an attribute that is guaranteed unique in your
529         directory, such as <code>uid</code>.
530 <highlight language="config">
531 AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"
532 Require valid-user
533 </highlight>
534       </li>
535
536       <li>
537         Grant access to anybody in the Administrators group. The
538         users must authenticate using their UID.
539 <highlight language="config">
540 AuthLDAPURL ldap://ldap.example.com/o=Example?uid
541 Require ldap-group cn=Administrators, o=Example
542 </highlight>
543       </li>
544
545       <li>
546         The next example assumes that everyone at Example who
547         carries an alphanumeric pager will have an LDAP attribute
548         of <code>qpagePagerID</code>. The example will grant access
549         only to people (authenticated via their UID) who have
550         alphanumeric pagers:
551 <highlight language="config">
552 AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)
553 Require valid-user
554 </highlight>
555       </li>
556
557       <li>
558         <p>The next example demonstrates the power of using filters
559         to accomplish complicated administrative requirements.
560         Without filters, it would have been necessary to create a
561         new LDAP group and ensure that the group's members remain
562         synchronized with the pager users. This becomes trivial
563         with filters. The goal is to grant access to anyone who has
564         a pager, plus grant access to Joe Manager, who doesn't
565         have a pager, but does need to access the same
566         resource:</p>
567 <highlight language="config">
568 AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(|(qpagePagerID=*)(uid=jmanager))
569 Require valid-user
570 </highlight>
571
572         <p>This last may look confusing at first, so it helps to
573         evaluate what the search filter will look like based on who
574         connects, as shown below.  If
575         Fred User connects as <code>fuser</code>, the filter would look
576         like</p>
577
578         <example>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))</example>
579
580         <p>The above search will only succeed if <em>fuser</em> has a
581         pager. When Joe Manager connects as <em>jmanager</em>, the
582         filter looks like</p>
583
584         <example>(&amp;(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))</example>
585
586         <p>The above search will succeed whether <em>jmanager</em>
587         has a pager or not.</p>
588       </li>
589     </ul>
590 </section>
591
592 <section id="usingtls"><title>Using TLS</title>
593
594     <p>To use TLS, see the <module>mod_ldap</module> directives <directive
595     module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
596     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
597     module="mod_ldap">LDAPTrustedMode</directive>.</p>
598
599     <p>An optional second parameter can be added to the
600     <directive module="mod_authnz_ldap">AuthLDAPURL</directive> to override
601     the default connection type set by <directive module="mod_ldap">LDAPTrustedMode</directive>.
602     This will allow the connection established by an <em>ldap://</em> Url
603     to be upgraded to a secure connection on the same port.</p>
604 </section>
605
606 <section id="usingssl"><title>Using SSL</title>
607
608     <p>To use SSL, see the <module>mod_ldap</module> directives <directive
609     module="mod_ldap">LDAPTrustedClientCert</directive>, <directive
610     module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
611     module="mod_ldap">LDAPTrustedMode</directive>.</p>
612
613     <p>To specify a secure LDAP server, use <em>ldaps://</em> in the
614     <directive module="mod_authnz_ldap">AuthLDAPURL</directive>
615     directive, instead of <em>ldap://</em>.</p>
616 </section>
617
618 <section id="exposed"><title>Exposing Login Information</title>
619
620     <p>when this module performs <em>authentication</em>, ldap attributes specified
621     in the <directive module="mod_authnz_ldap">authldapurl</directive>
622     directive are placed in environment variables with the prefix "AUTHENTICATE_".</p>
623
624     <p>when this module performs <em>authorization</em>, ldap attributes specified
625     in the <directive module="mod_authnz_ldap">authldapurl</directive>
626     directive are placed in environment variables with the prefix "AUTHORIZE_".</p>
627
628     <p>If the attribute field contains the username, common name
629     and telephone number of a user, a CGI program will have access to
630     this information without the need to make a second independent LDAP
631     query to gather this additional information.</p>
632
633     <p>This has the potential to dramatically simplify the coding and
634     configuration required in some web applications.</p>
635
636 </section>
637
638 <section id="activedirectory"><title>Using Active Directory</title>
639
640     <p>An Active Directory installation may support multiple domains at the
641     same time. To distinguish users between domains, an identifier called
642     a User Principle Name (UPN) can be added to a user's entry in the
643     directory. This UPN usually takes the form of the user's account
644     name, followed by the domain components of the particular domain,
645     for example <em>somebody@nz.example.com</em>.</p>
646
647     <p>You may wish to configure the <module>mod_authnz_ldap</module>
648     module to authenticate users present in any of the domains making up
649     the Active Directory forest. In this way both
650     <em>somebody@nz.example.com</em> and <em>someone@au.example.com</em>
651     can be authenticated using the same query at the same time.</p>
652
653     <p>To make this practical, Active Directory supports the concept of
654     a Global Catalog. This Global Catalog is a read only copy of selected
655     attributes of all the Active Directory servers within the Active
656     Directory forest. Querying the Global Catalog allows all the domains
657     to be queried in a single query, without the query spanning servers
658     over potentially slow links.</p>
659
660     <p>If enabled, the Global Catalog is an independent directory server
661     that runs on port 3268 (3269 for SSL). To search for a user, do a
662     subtree search for the attribute <em>userPrincipalName</em>, with
663     an empty search root, like so:</p>
664
665 <highlight language="config">
666 AuthLDAPBindDN apache@example.com
667 AuthLDAPBindPassword password
668 AuthLDAPURL ldap://10.0.0.1:3268/?userPrincipalName?sub
669 </highlight>
670
671     <p>Users will need to enter their User Principal Name as a login, in
672     the form <em>somebody@nz.example.com</em>.</p>
673
674 </section>
675
676 <section id="frontpage"><title>Using Microsoft
677     FrontPage with mod_authnz_ldap</title>
678
679     <p>Normally, FrontPage uses FrontPage-web-specific user/group
680     files (i.e., the <module>mod_authn_file</module> and
681     <module>mod_authz_groupfile</module> modules) to handle all
682     authentication. Unfortunately, it is not possible to just
683     change to LDAP authentication by adding the proper directives,
684     because it will break the <em>Permissions</em> forms in
685     the FrontPage client, which attempt to modify the standard
686     text-based authorization files.</p>
687
688     <p>Once a FrontPage web has been created, adding LDAP
689     authentication to it is a matter of adding the following
690     directives to <em>every</em> <code>.htaccess</code> file
691     that gets created in the web</p>
692 <highlight language="config">
693 AuthLDAPURL       "the url"
694 AuthGroupFile     mygroupfile
695 Require group     mygroupfile
696 </highlight>
697
698 <section id="howitworks"><title>How It Works</title>
699
700     <p>FrontPage restricts access to a web by adding the <code>Require
701     valid-user</code> directive to the <code>.htaccess</code>
702     files. The <code>Require valid-user</code> directive will succeed for
703     any user who is valid <em>as far as LDAP is
704     concerned</em>. This means that anybody who has an entry in
705     the LDAP directory is considered a valid user, whereas FrontPage
706     considers only those people in the local user file to be
707     valid. By substituting the ldap-group with group file authorization,
708     Apache is allowed to consult the local user file (which is managed by
709     FrontPage) - instead of LDAP - when handling authorizing the user.</p>
710
711     <p>Once directives have been added as specified above,
712     FrontPage users will be able to perform all management
713     operations from the FrontPage client.</p>
714 </section>
715
716 <section id="fpcaveats"><title>Caveats</title>
717
718     <ul>
719       <li>When choosing the LDAP URL, the attribute to use for
720       authentication should be something that will also be valid
721       for putting into a <module>mod_authn_file</module> user file.
722       The user ID is ideal for this.</li>
723
724       <li>When adding users via FrontPage, FrontPage administrators
725       should choose usernames that already exist in the LDAP
726       directory (for obvious reasons). Also, the password that the
727       administrator enters into the form is ignored, since Apache
728       will actually be authenticating against the password in the
729       LDAP database, and not against the password in the local user
730       file. This could cause confusion for web administrators.</li>
731
732       <!-- XXX is that true? was mod_auth before the aaa change -->
733       <li>Apache must be compiled with <module>mod_auth_basic</module>,
734       <module>mod_authn_file</module> and
735       <module>mod_authz_groupfile</module> in order to
736       use FrontPage support. This is because Apache will still use
737       the <module>mod_authz_groupfile</module> group file for determine
738       the extent of a user's access to the FrontPage web.</li>
739
740       <li>The directives must be put in the <code>.htaccess</code>
741       files. Attempting to put them inside <directive module="core"
742       type="section">Location</directive> or <directive module="core"
743       type="section">Directory</directive> directives won't work. This
744       is because <module>mod_authnz_ldap</module> has to be able to grab
745       the <directive module="mod_authz_groupfile">AuthGroupFile</directive>
746       directive that is found in FrontPage <code>.htaccess</code>
747       files so that it knows where to look for the valid user list. If
748       the <module>mod_authnz_ldap</module> directives aren't in the same
749       <code>.htaccess</code> file as the FrontPage directives, then
750       the hack won't work, because <module>mod_authnz_ldap</module> will
751       never get a chance to process the <code>.htaccess</code> file,
752       and won't be able to find the FrontPage-managed user file.</li>
753     </ul>
754 </section>
755 </section>
756
757 <directivesynopsis>
758 <name>AuthLDAPAuthorizePrefix</name>
759 <description>Specifies the prefix for environment variables set during
760 authorization</description>
761 <syntax>AuthLDAPAuthorizePrefix <em>prefix</em></syntax>
762 <default>AuthLDAPAuthorizePrefix AUTHORIZE_</default>
763 <contextlist><context>directory</context><context>.htaccess</context>
764 </contextlist>
765 <override>AuthConfig</override>
766 <compatibility>Available in version 2.3.6 and later</compatibility>
767 <usage>
768     <p>This directive allows you to override the prefix used for environment
769     variables set during LDAP authorization.  If <em>AUTHENTICATE_</em> is
770     specified, consumers of these environment variables see the same information
771     whether LDAP has performed authentication, authorization, or both.</p>
772
773     <note><title>Note</title>
774     No authorization variables are set when a user is authorized on the basis of
775     <code>Require valid-user</code>.
776     </note>
777 </usage>
778 </directivesynopsis>
779
780
781 <directivesynopsis>
782 <name>AuthLDAPBindAuthoritative</name>
783 <description>Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.</description>
784 <syntax>AuthLDAPBindAuthoritative<em>off|on</em></syntax>
785 <default>AuthLDAPBindAuthoritative on</default>
786 <contextlist><context>directory</context><context>.htaccess</context>
787 </contextlist>
788 <override>AuthConfig</override>
789 <usage>
790     <p>By default, subsequent authentication providers are only queried if a
791     user cannot be mapped to a DN, but not if the user can be mapped to a DN and their
792     password cannot be verified with an LDAP bind.
793     If <directive module="mod_authnz_ldap">AuthLDAPBindAuthoritative</directive>
794     is set to <em>off</em>, other configured authentication modules will have
795     a chance to validate the user if the LDAP bind (with the current user's credentials)
796     fails for any reason.</p>
797     <p> This allows users present in both LDAP and
798     <directive module="mod_authn_file">AuthUserFile</directive> to authenticate
799     when the LDAP server is available but the user's account is locked or password
800     is otherwise unusable.</p>
801 </usage>
802 <seealso><directive module="mod_authn_file">AuthUserFile</directive></seealso>
803 <seealso><directive module="mod_auth_basic">AuthBasicProvider</directive></seealso>
804 </directivesynopsis>
805
806 <directivesynopsis>
807 <name>AuthLDAPInitialBindAsUser</name>
808 <description>Determines if the server does the initial DN lookup using the basic authentication users'
809 own username, instead of anonymously or with hard-coded credentials for the server</description>
810 <syntax>AuthLDAPInitialBindAsUser <em>off|on</em></syntax>
811 <default>AuthLDAPInitialBindAsUser off</default>
812 <contextlist><context>directory</context><context>.htaccess</context>
813 </contextlist>
814 <override>AuthConfig</override>
815 <compatibility>Available in version 2.3.6 and later</compatibility>
816 <usage>
817     <p>By default, the server either anonymously, or with a dedicated user and
818      password, converts the basic authentication username into an LDAP
819      distinguished name (DN).  This directive forces the server to use the verbatim username
820      and password provided by the incoming user to perform the initial DN
821      search.</p>
822
823      <p> If the verbatim username can't directly bind, but needs some
824      cosmetic transformation, see <directive module="mod_authnz_ldap">
825      AuthLDAPInitialBindPattern</directive>.</p>
826
827      <p> This directive should only be used when your LDAP server doesn't
828          accept anonymous searches and you cannot use a dedicated
829          <directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
830      </p>
831
832      <note><title>Not available with authorization-only</title>
833          This directive can only be used if this module authenticates the user, and
834          has no effect when this module is used exclusively for authorization.
835      </note>
836 </usage>
837 <seealso><directive module="mod_authnz_ldap">AuthLDAPInitialBindPattern</directive></seealso>
838 <seealso><directive module="mod_authnz_ldap">AuthLDAPBindDN</directive></seealso>
839 <seealso><directive module="mod_authnz_ldap">AuthLDAPCompareAsUser</directive></seealso>
840 <seealso><directive module="mod_authnz_ldap">AuthLDAPSearchAsUser</directive></seealso>
841 </directivesynopsis>
842
843 <directivesynopsis>
844 <name>AuthLDAPInitialBindPattern</name>
845 <description>Specifies the transformation of the basic authentication username to be used when binding to the LDAP server
846 to perform a DN lookup</description>
847 <syntax>AuthLDAPInitialBindPattern<em><var>regex</var> <var>substitution</var></em></syntax>
848 <default>AuthLDAPInitialBindPattern (.*) $1 (remote username used verbatim)</default>
849 <contextlist><context>directory</context><context>.htaccess</context>
850 </contextlist>
851 <override>AuthConfig</override>
852 <compatibility>Available in version 2.3.6 and later</compatibility>
853 <usage>
854     <p>If <directive module="mod_authnz_ldap">AuthLDAPInitialBindAsUser</directive> is set to
855        <em>ON</em>, the basic authentication username will be transformed according to the
856        regular expression and substituion arguments.</p>
857
858     <p> The regular expression argument is compared against the current basic authentication username.
859         The substitution argument may contain backreferences, but has no other variable interpolation.</p>
860
861     <p> This directive should only be used when your LDAP server doesn't
862         accept anonymous searches and you cannot use a dedicated
863         <directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
864     </p>
865
866     <highlight language="config"> AuthLDAPInitialBindPattern (.+) $1@example.com </highlight>
867     <highlight language="config"> AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com</highlight>
868
869     <note><title>Not available with authorization-only</title>
870         This directive can only be used if this module authenticates the user, and
871         has no effect when this module is used exclusively for authorization.
872     </note>
873     <note><title>debugging</title>
874         The substituted DN is recorded in the environment variable
875         <em>LDAP_BINDASUSER</em>.  If the regular expression does not match the input,
876         the verbatim username is used.
877     </note>
878 </usage>
879 <seealso><directive module="mod_authnz_ldap">AuthLDAPInitialBindAsUser</directive></seealso>
880 <seealso><directive module="mod_authnz_ldap">AuthLDAPBindDN</directive></seealso>
881 </directivesynopsis>
882
883 <directivesynopsis>
884 <name>AuthLDAPBindDN</name>
885 <description>Optional DN to use in binding to the LDAP server</description>
886 <syntax>AuthLDAPBindDN <em>distinguished-name</em></syntax>
887 <contextlist><context>directory</context><context>.htaccess</context>
888 </contextlist>
889 <override>AuthConfig</override>
890
891 <usage>
892     <p>An optional DN used to bind to the server when searching for
893     entries. If not provided, <module>mod_authnz_ldap</module> will use
894     an anonymous bind.</p>
895 </usage>
896 </directivesynopsis>
897
898 <directivesynopsis>
899 <name>AuthLDAPBindPassword</name>
900 <description>Password used in conjuction with the bind DN</description>
901 <syntax>AuthLDAPBindPassword <em>password</em></syntax>
902 <contextlist><context>directory</context><context>.htaccess</context>
903 </contextlist>
904 <override>AuthConfig</override>
905
906 <usage>
907     <p>A bind password to use in conjunction with the bind DN. Note
908     that the bind password is probably sensitive data, and should be
909     properly protected. You should only use the <directive
910     module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
911     module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
912     absolutely need them to search the directory.</p>
913 </usage>
914 </directivesynopsis>
915
916 <directivesynopsis>
917 <name>AuthLDAPCharsetConfig</name>
918 <description>Language to charset conversion configuration file</description>
919 <syntax>AuthLDAPCharsetConfig <em>file-path</em></syntax>
920 <contextlist><context>server config</context>
921 </contextlist>
922
923 <usage>
924     <p>The <directive>AuthLDAPCharsetConfig</directive> directive sets the location
925     of the language to charset conversion configuration file. <var>File-path</var> is relative
926     to the <directive module="core">ServerRoot</directive>. This file specifies
927     the list of language extensions to character sets.
928     Most administrators use the provided <code>charset.conv</code>
929     file, which associates common language extensions to character sets.</p>
930
931     <p>The file contains lines in the following format:</p>
932
933     <example>
934       <var>Language-Extension</var> <var>charset</var> [<var>Language-String</var>] ...
935     </example>
936
937     <p>The case of the extension does not matter. Blank lines, and lines
938     beginning with a hash character (<code>#</code>) are ignored.</p>
939 </usage>
940 </directivesynopsis>
941
942 <directivesynopsis>
943 <name>AuthLDAPCompareAsUser</name>
944 <description>Use the authenticated user's credentials to perform authorization comparisons</description>
945 <syntax>AuthLDAPCompareAsUser on|off</syntax>
946 <default>AuthLDAPCompareAsUser off</default>
947 <contextlist><context>directory</context><context>.htaccess</context>
948 </contextlist>
949 <override>AuthConfig</override>
950 <compatibility>Available in version 2.3.6 and later</compatibility>
951
952 <usage>
953     <p>When set, and <module>mod_authnz_ldap</module> has authenticated the
954     user, LDAP comparisons for authorization use the queried distinguished name (DN)
955     and HTTP basic authentication password of the authenticated user instead of
956     the servers configured credentials.</p>
957
958     <p> The <em>ldap-attribute</em>, <em>ldap-user</em>, and <em>ldap-group</em> (single-level only)
959     authorization checks use comparisons.</p>
960
961     <p>This directive only has effect on the comparisons performed during
962     nested group processing when <directive module="mod_authnz_ldap">
963     AuthLDAPSearchAsUser</directive> is also enabled.</p>
964
965     <p> This directive should only be used when your LDAP server doesn't
966         accept anonymous comparisons and you cannot use a dedicated
967         <directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
968     </p>
969 </usage>
970 <seealso><directive module="mod_authnz_ldap">AuthLDAPInitialBindAsUser</directive></seealso>
971 <seealso><directive module="mod_authnz_ldap">AuthLDAPSearchAsUser</directive></seealso>
972 </directivesynopsis>
973
974 <directivesynopsis>
975 <name>AuthLDAPCompareDNOnServer</name>
976 <description>Use the LDAP server to compare the DNs</description>
977 <syntax>AuthLDAPCompareDNOnServer on|off</syntax>
978 <default>AuthLDAPCompareDNOnServer on</default>
979 <contextlist><context>directory</context><context>.htaccess</context>
980 </contextlist>
981 <override>AuthConfig</override>
982
983 <usage>
984     <p>When set, <module>mod_authnz_ldap</module> will use the LDAP
985     server to compare the DNs. This is the only foolproof way to
986     compare DNs.  <module>mod_authnz_ldap</module> will search the
987     directory for the DN specified with the <a
988     href="#reqdn"><code>Require dn</code></a> directive, then,
989     retrieve the DN and compare it with the DN retrieved from the user
990     entry. If this directive is not set,
991     <module>mod_authnz_ldap</module> simply does a string comparison. It
992     is possible to get false negatives with this approach, but it is
993     much faster. Note the <module>mod_ldap</module> cache can speed up
994     DN comparison in most situations.</p>
995 </usage>
996 </directivesynopsis>
997
998 <directivesynopsis>
999 <name>AuthLDAPDereferenceAliases</name>
1000 <description>When will the module de-reference aliases</description>
1001 <syntax>AuthLDAPDereferenceAliases never|searching|finding|always</syntax>
1002 <default>AuthLDAPDereferenceAliases always</default>
1003 <contextlist><context>directory</context><context>.htaccess</context>
1004 </contextlist>
1005 <override>AuthConfig</override>
1006
1007 <usage>
1008     <p>This directive specifies when <module>mod_authnz_ldap</module> will
1009     de-reference aliases during LDAP operations. The default is
1010     <code>always</code>.</p>
1011 </usage>
1012 </directivesynopsis>
1013
1014 <directivesynopsis>
1015 <name>AuthLDAPGroupAttribute</name>
1016 <description>LDAP attributes used to identify the user members of
1017 groups.</description>
1018 <syntax>AuthLDAPGroupAttribute <em>attribute</em></syntax>
1019 <default>AuthLDAPGroupAttribute member uniquemember</default>
1020 <contextlist><context>directory</context><context>.htaccess</context>
1021 </contextlist>
1022 <override>AuthConfig</override>
1023
1024 <usage>
1025     <p>This directive specifies which LDAP attributes are used to
1026     check for user members within groups. Multiple attributes can be used
1027     by specifying this directive multiple times. If not specified,
1028     then <module>mod_authnz_ldap</module> uses the <code>member</code> and
1029     <code>uniquemember</code> attributes.</p>
1030 </usage>
1031 </directivesynopsis>
1032
1033 <directivesynopsis>
1034 <name>AuthLDAPGroupAttributeIsDN</name>
1035 <description>Use the DN of the client username when checking for
1036 group membership</description>
1037 <syntax>AuthLDAPGroupAttributeIsDN on|off</syntax>
1038 <default>AuthLDAPGroupAttributeIsDN on</default>
1039 <contextlist><context>directory</context><context>.htaccess</context>
1040 </contextlist>
1041 <override>AuthConfig</override>
1042
1043 <usage>
1044     <p>When set <code>on</code>, this directive says to use the
1045     distinguished name of the client username when checking for group
1046     membership.  Otherwise, the username will be used. For example,
1047     assume that the client sent the username <code>bjenson</code>,
1048     which corresponds to the LDAP DN <code>cn=Babs Jenson,
1049     o=Example</code>. If this directive is set,
1050     <module>mod_authnz_ldap</module> will check if the group has
1051     <code>cn=Babs Jenson, o=Example</code> as a member. If this
1052     directive is not set, then <module>mod_authnz_ldap</module> will
1053     check if the group has <code>bjenson</code> as a member.</p>
1054 </usage>
1055 </directivesynopsis>
1056
1057 <directivesynopsis>
1058 <name>AuthLDAPMaxSubGroupDepth</name>
1059 <description>Specifies the maximum sub-group nesting depth that will be
1060 evaluated before the user search is discontinued.</description>
1061 <syntax>AuthLDAPMaxSubGroupDepth <var>Number</var></syntax>
1062 <default>AuthLDAPMaxSubGroupDepth 10</default>
1063 <contextlist><context>directory</context><context>.htaccess</context>
1064 </contextlist>
1065 <override>AuthConfig</override>
1066 <compatibility>Available in version 2.3.0 and later</compatibility>
1067
1068 <usage>
1069    <p>When this directive is set to a non-zero value <code>X</code>
1070    combined with use of the <code>Require ldap-group someGroupDN</code>
1071    directive, the provided user credentials will be searched for
1072    as a member of the <code>someGroupDN</code> directory object or of
1073    any group member of the current group up to the maximum nesting
1074    level <code>X</code> specified by this directive.</p>
1075    <p>See the <a href="#reqgroup"><code>Require ldap-group</code></a>
1076    section for a more detailed example.</p>
1077 </usage>
1078 </directivesynopsis>
1079
1080 <directivesynopsis>
1081 <name>AuthLDAPRemoteUserAttribute</name>
1082 <description>Use the value of the attribute returned during the user
1083 query to set the REMOTE_USER environment variable</description>
1084 <syntax>AuthLDAPRemoteUserAttribute uid</syntax>
1085 <default>none</default>
1086 <contextlist><context>directory</context><context>.htaccess</context>
1087 </contextlist>
1088 <override>AuthConfig</override>
1089
1090 <usage>
1091     <p>If this directive is set, the value of the
1092     <code>REMOTE_USER</code> environment variable will be set to the
1093     value of the attribute specified. Make sure that this attribute is
1094     included in the list of attributes in the AuthLDAPUrl definition,
1095     otherwise this directive will have no effect. This directive, if
1096     present, takes precedence over AuthLDAPRemoteUserIsDN. This
1097     directive is useful should you want people to log into a website
1098     using an email address, but a backend application expects the
1099     username as a userid.</p>
1100 </usage>
1101 </directivesynopsis>
1102
1103 <directivesynopsis>
1104 <name>AuthLDAPRemoteUserIsDN</name>
1105 <description>Use the DN of the client username to set the REMOTE_USER
1106 environment variable</description>
1107 <syntax>AuthLDAPRemoteUserIsDN on|off</syntax>
1108 <default>AuthLDAPRemoteUserIsDN off</default>
1109 <contextlist><context>directory</context><context>.htaccess</context>
1110 </contextlist>
1111 <override>AuthConfig</override>
1112
1113 <usage>
1114     <p>If this directive is set to on, the value of the
1115     <code>REMOTE_USER</code> environment variable will be set to the full
1116     distinguished name of the authenticated user, rather than just
1117     the username that was passed by the client. It is turned off by
1118     default.</p>
1119 </usage>
1120 </directivesynopsis>
1121
1122 <directivesynopsis>
1123 <name>AuthLDAPSearchAsUser</name>
1124 <description>Use the authenticated user's credentials to perform authorization searches</description>
1125 <syntax>AuthLDAPSearchAsUser on|off</syntax>
1126 <default>AuthLDAPSearchAsUser off</default>
1127 <contextlist><context>directory</context><context>.htaccess</context>
1128 </contextlist>
1129 <override>AuthConfig</override>
1130 <compatibility>Available in version 2.3.6 and later</compatibility>
1131
1132 <usage>
1133     <p>When set, and <module>mod_authnz_ldap</module> has authenticated the
1134     user, LDAP searches for authorization use the queried distinguished name (DN)
1135     and HTTP basic authentication password of the authenticated user instead of
1136     the servers configured credentials.</p>
1137
1138     <p> The <em>ldap-filter</em> and <em>ldap-dn</em> authorization
1139     checks use searches.</p>
1140
1141     <p>This directive only has effect on the comparisons performed during
1142     nested group processing when <directive module="mod_authnz_ldap">
1143     AuthLDAPCompareAsUser</directive> is also enabled.</p>
1144
1145     <p> This directive should only be used when your LDAP server doesn't
1146         accept anonymous searches and you cannot use a dedicated
1147         <directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
1148     </p>
1149 </usage>
1150 <seealso><directive module="mod_authnz_ldap">AuthLDAPInitialBindAsUser</directive></seealso>
1151 <seealso><directive module="mod_authnz_ldap">AuthLDAPCompareAsUser</directive></seealso>
1152 </directivesynopsis>
1153
1154 <directivesynopsis>
1155 <name>AuthLDAPSubGroupAttribute</name>
1156 <description>Specifies the attribute labels, one value per
1157 directive line, used to distinguish the members of the current group that
1158 are groups.</description>
1159 <syntax>AuthLDAPSubGroupAttribute <em>attribute</em></syntax>
1160 <default>AuthLDAPSubgroupAttribute member uniquemember</default>
1161 <contextlist><context>directory</context><context>.htaccess</context>
1162 </contextlist>
1163 <override>AuthConfig</override>
1164 <compatibility>Available in version 2.3.0 and later</compatibility>
1165
1166 <usage>
1167     <p>An LDAP group object may contain members that are users and
1168     members that are groups (called nested or sub groups). The
1169     <code>AuthLDAPSubGroupAttribute</code> directive identifies the
1170     labels of group members and the <code>AuthLDAPGroupAttribute</code>
1171     directive identifies the labels of the user members. Multiple
1172     attributes can be used by specifying this directive multiple times.
1173     If not specified, then <module>mod_authnz_ldap</module> uses the
1174     <code>member</code> and <code>uniqueMember</code> attributes.</p>
1175 </usage>
1176 </directivesynopsis>
1177
1178 <directivesynopsis>
1179 <name>AuthLDAPSubGroupClass</name>
1180 <description>Specifies which LDAP objectClass values identify directory
1181 objects that are groups during sub-group processing.</description>
1182 <syntax>AuthLDAPSubGroupClass <em>LdapObjectClass</em></syntax>
1183 <default>AuthLDAPSubGroupClass groupOfNames groupOfUniqueNames</default>
1184 <contextlist><context>directory</context><context>.htaccess</context>
1185 </contextlist>
1186 <override>AuthConfig</override>
1187 <compatibility>Available in version 2.3.0 and later</compatibility>
1188
1189 <usage>
1190     <p>An LDAP group object may contain members that are users and
1191     members that are groups (called nested or sub groups). The
1192     <code>AuthLDAPSubGroupAttribute</code> directive identifies the
1193     labels of members that may be sub-groups of the current group
1194     (as opposed to user members). The <code>AuthLDAPSubGroupClass</code>
1195     directive specifies the LDAP objectClass values used in verifying that
1196     these potential sub-groups are in fact group objects. Verified sub-groups
1197     can then be searched for more user or sub-group members. Multiple
1198     attributes can be used by specifying this directive multiple times.
1199     If not specified, then <module>mod_authnz_ldap</module> uses the
1200     <code>groupOfNames</code> and <code>groupOfUniqueNames</code> values.</p>
1201 </usage>
1202 </directivesynopsis>
1203
1204 <directivesynopsis>
1205 <name>AuthLDAPUrl</name>
1206 <description>URL specifying the LDAP search parameters</description>
1207 <syntax>AuthLDAPUrl <em>url [NONE|SSL|TLS|STARTTLS]</em></syntax>
1208 <contextlist><context>directory</context><context>.htaccess</context>
1209 </contextlist>
1210 <override>AuthConfig</override>
1211
1212 <usage>
1213     <p>An RFC 2255 URL which specifies the LDAP search parameters
1214     to use. The syntax of the URL is</p>
1215 <example>ldap://host:port/basedn?attribute?scope?filter</example>
1216     <p>If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:</p>
1217 <highlight language="config">AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."</highlight>
1218 <p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
1219 otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
1220 You can of course use search parameters on each of these.</p>
1221
1222 <dl>
1223 <dt>ldap</dt>
1224
1225         <dd>For regular ldap, use the
1226         string <code>ldap</code>. For secure LDAP, use <code>ldaps</code>
1227         instead. Secure LDAP is only available if Apache was linked
1228         to an LDAP library with SSL support.</dd>
1229
1230 <dt>host:port</dt>
1231
1232         <dd>
1233           <p>The name/port of the ldap server (defaults to
1234           <code>localhost:389</code> for <code>ldap</code>, and
1235           <code>localhost:636</code> for <code>ldaps</code>). To
1236           specify multiple, redundant LDAP servers, just list all
1237           servers, separated by spaces. <module>mod_authnz_ldap</module>
1238           will try connecting to each server in turn, until it makes a
1239           successful connection. If multiple ldap servers are specified,
1240           then entire LDAP URL must be encapsulated in double quotes.</p>
1241
1242           <p>Once a connection has been made to a server, that
1243           connection remains active for the life of the
1244           <program>httpd</program> process, or until the LDAP server goes
1245           down.</p>
1246
1247           <p>If the LDAP server goes down and breaks an existing
1248           connection, <module>mod_authnz_ldap</module> will attempt to
1249           re-connect, starting with the primary server, and trying
1250           each redundant server in turn. Note that this is different
1251           than a true round-robin search.</p>
1252         </dd>
1253
1254 <dt>basedn</dt>
1255
1256         <dd>The DN of the branch of the
1257         directory where all searches should start from. At the very
1258         least, this must be the top of your directory tree, but
1259         could also specify a subtree in the directory.</dd>
1260
1261 <dt>attribute</dt>
1262
1263         <dd>The attribute to search for.
1264         Although RFC 2255 allows a comma-separated list of
1265         attributes, only the first attribute will be used, no
1266         matter how many are provided. If no attributes are
1267         provided, the default is to use <code>uid</code>. It's a good
1268         idea to choose an attribute that will be unique across all
1269         entries in the subtree you will be using.  All attributes
1270         listed will be put into the environment with an AUTHENTICATE_ prefix
1271         for use by other modules.</dd>
1272
1273 <dt>scope</dt>
1274
1275         <dd>The scope of the search. Can be either <code>one</code> or
1276         <code>sub</code>. Note that a scope of <code>base</code> is
1277         also supported by RFC 2255, but is not supported by this
1278         module. If the scope is not provided, or if <code>base</code> scope
1279         is specified, the default is to use a scope of
1280         <code>sub</code>.</dd>
1281
1282 <dt>filter</dt>
1283
1284         <dd>A valid LDAP search filter. If
1285         not provided, defaults to <code>(objectClass=*)</code>, which
1286         will search for all objects in the tree. Filters are
1287         limited to approximately 8000 characters (the definition of
1288         <code>MAX_STRING_LEN</code> in the Apache source code). This
1289         should be more than sufficient for any application.</dd>
1290 </dl>
1291
1292     <p>When doing searches, the attribute, filter and username passed
1293     by the HTTP client are combined to create a search filter that
1294     looks like
1295     <code>(&amp;(<em>filter</em>)(<em>attribute</em>=<em>username</em>))</code>.</p>
1296
1297     <p>For example, consider an URL of
1298     <code>ldap://ldap.example.com/o=Example?cn?sub?(posixid=*)</code>. When
1299     a client attempts to connect using a username of <code>Babs
1300     Jenson</code>, the resulting search filter will be
1301     <code>(&amp;(posixid=*)(cn=Babs Jenson))</code>.</p>
1302
1303     <p>An optional parameter can be added to allow the LDAP Url to override
1304     the connection type.  This parameter can be one of the following:</p>
1305
1306 <dl>
1307     <dt>NONE</dt>
1308         <dd>Establish an unsecure connection on the default LDAP port. This
1309         is the same as <code>ldap://</code> on port 389.</dd>
1310     <dt>SSL</dt>
1311         <dd>Establish a secure connection on the default secure LDAP port.
1312         This is the same as <code>ldaps://</code></dd>
1313     <dt>TLS | STARTTLS</dt>
1314         <dd>Establish an upgraded secure connection on the default LDAP port.
1315         This connection will be initiated on port 389 by default and then
1316         upgraded to a secure connection on the same port.</dd>
1317 </dl>
1318
1319     <p>See above for examples of <directive
1320     module="mod_authnz_ldap">AuthLDAPURL</directive> URLs.</p>
1321 </usage>
1322 </directivesynopsis>
1323
1324 </modulesynopsis>