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