From: Bradley Nicholes Date: Thu, 22 Aug 2002 18:21:31 +0000 (+0000) Subject: Adding the LDAP docs back into the LDAP project. They didn't seem to make X-Git-Tag: AGB_BEFORE_AAA_CHANGES~190 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=22c671d0e0f830dab4e2d2e57d0d9147601fc6c4;p=apache Adding the LDAP docs back into the LDAP project. They didn't seem to make it when the httpd-ldap project was created. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96488 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_auth_ldap.html b/docs/manual/mod/mod_auth_ldap.html new file mode 100644 index 0000000000..6dd005994b --- /dev/null +++ b/docs/manual/mod/mod_auth_ldap.html @@ -0,0 +1,989 @@ + + + + + + + Apache module mod_ldap + + + + + + + +

Module mod_auth_ldap

+ +

This is an authentication module that allows Apache to + authenticate HTTP clients using user entries in an LDAP + directory.

+ +

Status: Extension
+ Source File: util_ldap.c
+ Module Identifier: + ldap_module
+ Compatibility: Available in + Apache 2.0 and later.

+ +

Summary

+ +

mod_auth_ldap supports the following features:

+ + + +

Directives

+ + + +

Contents

+ + + +

Operation

+ +

There are two phases in granting access to a user. The first + phase is authentication, in which mod_auth_ldap verifies that + the user's credentials are valid. This also called the + search/bind phase. The second phase is + authorization, in which mod_auth_ldap determines if the + authenticated user is allowed access to the resource in + question. This is also known as the compare + phase.

+ +

The Authentication + Phase

+ +

During the authentication phase, mod_auth_ldap searches for + an entry in the directory that matches the username that the + HTTP client passes. If a single unique match is found, then + mod_auth_ldap attempts to bind to the directory server using + the DN of the entry plus the password provided by the HTTP + client. Because it does a search, then a bind, it is often + referred to as the search/bind phase. Here are the steps taken + during the search/bind phase.

+ +
    +
  1. Generate a search filter by combining the attribute and + filter provided in the AuthLDAPURL directive with + the username passed by the HTTP client.
    2. + +
  2. Search the directory using the generated filter. If the + search does not return exactly one entry, deny or decline + access.
    3. + +
  3. Fetch the distinguished name of the entry retrieved from + the search and attempt to bind to the LDAP server using the + DN and the password passed by the HTTP client. If the bind is + unsuccessful, deny or decline access.
    4. +
+ +

The following directives are used during the search/bind + phase

+ + + + + + + + + + + + + + + + + + + +
AuthLDAPURL Specifies the LDAP server, the + base DN, the attribute to use in the search, as well as the + extra search filter to use.
AuthLDAPBindDN An optional DN to bind with + during the search phase.
AuthLDAPBindPassword An optional password to bind + with during the search phase.
+ +

The Authorization + Phase

+ +

During the authorization phase, mod_auth_ldap attempts to + determine if the user is authorized to access the resource. + Many of these checks require mod_auth_ldap to do a compare + operation on the LDAP server. This is why this phase is often + referred to as the compare phase. mod_auth_ldap accepts the + following require + directives to determine if the credentials are + acceptable:

+ + + +

mod_auth_ldap uses the following directives during the + compare phase:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
AuthLDAPURL The attribute specified in the + URL is used in compare operations for the require + user operation.
AuthLDAPCompareDNOnServer + Determines the behavior of the + require dn directive.
AuthLDAPGroupAttribute + Determines the attribute to + use for comparisons in the require group + directive.
AuthLDAPGroupAttributeIsDN + Specifies whether to use the + user DN or the username when doing comparisons for the + require group directive.
+ +

The + require Directives

+ +

Apache's require directives are used during the + authorization phase to ensure that a user is allowed to access + a resource.

+ +

require + valid-user

+ +

If this directive exists, mod_auth_ldap grants access to any + user that has successfully authenticated during the search/bind + phase.

+ +

require user

+ +

The require user directive specifies what usernames + can access the resource. Once mod_auth_ldap has retrieved a + unique DN from the directory, it does an LDAP compare operation + using the username specified in the require user to + see if that username is part of the just-fetched LDAP entry. + Multiple users can be granted access by putting multiple + usernames on the line, separated with spaces. If a username has + a space in it, then it must be the only user on the line. In + this case, multiple users can be granted access by using + multiple require user directives, with one user per + line. For example, with a AuthLDAPURL of + ldap://ldap/o=Airius?cn (i.e., cn is used for + searches), the following require directives could be used to + restrict access:

+
+require user Barbara Jenson
+require user Fred User
+require user Joe Manager
+
+ +

Because of the way that mod_auth_ldap handles this + directive, Barbara Jenson could sign on as Barbara + Jenson, Babs Jenson or any other cn that + she has in her LDAP entry. Only the single require + user line is needed to support all values of the attribute + in the user's entry.

+ +

If the uid attribute was used instead of the + cn attribute in the URL above, the above three lines + could be condensed to

+
+require user bjenson fuser jmanager
+
+ +

require group

+ +

This directive specifies an LDAP group whose members are + allowed access. It takes the distinguished name of the LDAP + group. For example, assume that the following entry existed in + the LDAP directory:

+
+dn: cn=Administrators, o=Airius
+objectClass: groupOfUniqueNames
+uniqueMember: cn=Barbara Jenson, o=Airius
+uniqueMember: cn=Fred User, o=Airius
+
+ +

The following directive would grant access to both Fred and + Barbara:

+
+require group cn=Administrators, o=Airius
+
+ +

Behavior of this directive is modified by the AuthLDAPGroupAttribute + and AuthLDAPGroupAttributeIsDN + directives.

+ +

require dn

+ +

The require dn directive allows the administrator + to grant access based on distinguished names. It specifies a DN + that must match for access to be granted. If the distinguished + name that was retrieved from the directory server matches the + distinguished name in the require dn, then + authorization is granted.

+ +

The following directive would grant access to a specific + DN:

+
+require dn cn=Barbara Jenson, o=Airius
+
+ +

Behavior of this directive is modified by the AuthLDAPCompareDNOnServer + directive.

+ +

Examples

+ + + +

Using TLS

+ +

To use TLS, simply set the AuthLDAPStartTLS to on. + Nothing else needs to be done (other than ensure that your LDAP + server is configured for TLS).

+ +

Using SSL

+ +

If mod_auth_ldap is linked against the Netscape/iPlanet LDAP + SDK, it will not talk to any SSL server unless that server has + a certificate signed by a known Certificate Authority. As part + of the configuration mod_auth_ldap needs to be told where it + can find a database containing the known CAs. This database is + in the same format as Netscape Communicator's cert7.db + database. The easiest way to get this file is to start up a + fresh copy of Netscape, and grab the resulting + $HOME/.netscape/cert7.db file.

+ +

To specify a secure LDAP server, use ldaps:// in the + AuthLDAPURL directive, instead of ldap://.

+ +

Using Microsoft + FrontPage with mod_auth_ldap

+ +

Normally, FrontPage uses FrontPage-web-specific user/group + files (i.e., the mod_auth module) to handle all + authentication. Unfortunately, it is not possible to just + change to LDAP authentication by adding the proper directives, + because it will break the Permissions forms in + the FrontPage client, which attempt to modify the standard + text-based authorization files.

+ +

Once a FrontPage web has been created, adding LDAP + authentication to it is a matter of adding the following + directives to every .htaccess file + that gets created in the web

+
+AuthLDAPURL            the url
+AuthLDAPAuthoritative  off
+AuthLDAPFrontPageHack  on
+
+ +

AuthLDAPAuthoritative must be off to allow + mod_auth_ldap to decline group authentication so that Apache + will fall back to file authentication for checking group + membership. This allows the FrontPage-managed group file to be + used.

+ +

How It Works

+ +

FrontPage restricts access to a web by adding the + require valid-user directive to the .htaccess + files. If AuthLDAPFrontPageHack is not on, the + require valid-user directive will succeed for any user + who is valid as far as LDAP is concerned. This + means that anybody who has an entry in the LDAP directory is + considered a valid user, whereas FrontPage considers only those + people in the local user file to be valid. The purpose of the + hack is to force Apache to consult the local user file (which + is managed by FrontPage) - instead of LDAP - when handling the + require valid-user directive.

+ +

Once directives have been added as specified above, + FrontPage users will be able to perform all management + operations from the FrontPage client.

+ +

Caveats

+ + +
+ +

AuthLDAPAuthoritative + directive

+ +

Syntax: AuthLDAPAuthoritative + on|off
+ Default: + AuthLDAPAuthoritative on
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

Set to off if this module should let other + authentication modules attempt to authenticate the user, should + authentication with this module fail. Control is only passed on + to lower modules if there is no DN or rule that matches the + supplied user name (as passed by the client).

+
+ +

AuthLDAPBindDN + directive

+ +

Syntax: AuthLDAPBindDN + distinguished-name
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

An optional DN used to bind to the server when searching for + entries. If not provided, mod_auth_ldap will use an anonymous + bind.

+
+ +

AuthLDAPBindPassword + directive

+ +

Syntax: AuthLDAPBindPassword + password
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

A bind password to use in conjunction with the bind DN. Note + that the bind password is probably sensitive data, and should + be properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword + if you absolutely need them to search the directory.

+
+ +

AuthLDAPCompareDNOnServer + directive

+ +

Syntax: + AuthLDAPCompareDNOnServer on|off
+ Default: + AuthLDAPCompareDNOnServer on
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

When set, mod_auth_ldap will use the LDAP server to compare + the DNs. This is the only foolproof way to compare DNs. + mod_auth_ldap will search the directory for the DN specified + with the require dn directive, + then, retrieve the DN and compare it with the DN retrieved from + the user entry. If this directive is not set, mod_auth_ldap + simply does a string comparison. It is possible to get false + negatives with this approach, but it is much faster. Note the + mod_ldap cache can speed up DN comparison in most + situations.

+
+ +

AuthLDAPDereferenceAliases + directive

+ +

Syntax: + AuthLDAPDereferenceAliases never|searching|finding|always
+ Default: + AuthLDAPDereferenceAliases Always
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

This directive specifies when mod_auth_ldap will + de-reference aliases during LDAP operations. The default is + always.

+
+ +

AuthLDAPEnabled directive

+ +

Syntax: AuthLDAPEnabled + on|off
+ Default: AuthLDAPEnabled + on
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

Set to off to disable mod_auth_ldap in certain + directories. This is useful if you have mod_auth_ldap enabled + at or near the top of your tree, but want to disable it + completely in certain locations.

+
+ +

AuthLDAPFrontPageHack + directive

+ +

Syntax: AuthLDAPFrontPageHack + on|off
+ Default: + AuthLDAPFronPageHack off
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

See the section on using Microsoft + FrontPage with mod_auth_ldap.

+
+ +

AuthLDAPGroupAttribute + directive

+ +

Syntax: AuthLDAPGroupAttribute + attribute
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

This directive specifies which LDAP attributes are used to + check for group membership. Multiple attributes can be used by + specifying this directive multiple times. If not specified, + then mod_auth_ldap uses the member and + uniquemember attributes.

+
+ +

AuthLDAPGroupAttributeIsDN + directive

+ +

Syntax: + AuthLDAPGroupAttributeIsDN on|off
+ Default: + AuthLDAPGroupAttributeIsDN on
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

When set, this directive says to use the distinguished name + of the client username when checking for group membership. + Otherwise, the username will be used. For example, assume that + the client sent the username bjenson, which corresponds + to the LDAP DN cn=Babs Jenson, o=Airius. If this + directive is set, mod_auth_ldap will check if the group has + cn=Babs Jenson, o=Airius as a member. If this directive + is not set, then mod_auth_ldap will check if the group has + bjenson as a member.

+
+ +

AuthLDAPRemoteUserIsDN + directive

+ +

Syntax: AuthLDAPRemoteUserIsDN + on|off
+ Default: AuthLDAPUserIsDN + off
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

If this directive is set to on, the value of the + REMOTE_USER environment variable will be set to the full + distinguished name of the authenticated user, rather than just + the username that was passed by the client. It is turned off by + default.

+
+ +

AuthLDAPStartTLS directive

+ +

Syntax: AuthLDAPStartTLS + on|off
+ Default: AuthLDAPStartTLS + off
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

If this directive is set to on, mod_auth_ldap will start a + secure TLS session after connecting to the LDAP server. This + requires your LDAP server to support TLS.

+
+ +

AuthLDAPUrl + directive

+ +

Syntax: AuthLDAPUrl + url
+ Context: directory, + .htaccess
+ Override: AuthConfig
+ Status: Extension
+ Module: mod_auth_ldap

+ +

An RFC 2255 URL which specifies the LDAP search parameters + to use. The syntax of the URL is

+
+ldap://host:port/basedn?attribute?scope?filter
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ldapFor regular ldap, use the + string ldap. For secure LDAP, use ldaps + instead. Secure LDAP is only available if Apache was linked + to an LDAP library with SSL support.
host:port +

The name/port of the ldap server (defaults to + localhost:389 for ldap, and + localhost:636 for ldaps). To specify + multiple, redundant LDAP servers, just list all servers, + separated by spaces. mod_auth_ldap will try connecting to + each server in turn, until it makes a successful + connection.

+ +

Once a connection has been made to a server, that + connection remains active for the life of the + httpd process, or until the LDAP server goes + down.

+ +

If the LDAP server goes down and breaks an existing + connection, mod_auth_ldap will attempt to re-connect, + starting with the primary server, and trying each + redundant server in turn. Note that this is different + than a true round-robin search.

+
basednThe DN of the branch of the + directory where all searches should start from. At the very + least, this must be the top of your directory tree, but + could also specify a subtree in the directory.
attributeThe attribute to search for. + Although RFC 2255 allows a comma-separated list of + attributes, only the first attribute will be used, no + matter how many are provided. If no attributes are + provided, the default is to use uid. It's a good + idea to choose an attribute that will be unique across all + entries in the subtree you will be using.
scopeThe scope of the search. Can + be either one or sub. Note that a scope of + base is also supported by RFC 2255, but is not + supported by this module. If the scope is not provided, or + if base scope is specified, the default is to use a + scope of sub.
filterA valid LDAP search filter. If + not provided, defaults to (objectClass=*), which + will search for all objects in the tree. Filters are + limited to approximately 8000 characters (the definition of + MAX_STRING_LEN in the Apache source code). This + should be than sufficient for any application.
+ +

When doing searches, the attribute, filter and username + passed by the HTTP client are combined to create a search + filter that looks like + (&(filter)(attribute=username)).

+ +

For example, consider an URL of + ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*). When + a client attempts to connect using a username of Babs + Jenson, the resulting search filter will be + (&(posixid=*)(cn=Babs Jenson)).

+ +

See above for examples of AuthLDAPURL URLs.

+ + + + diff --git a/docs/manual/mod/mod_ldap.html b/docs/manual/mod/mod_ldap.html new file mode 100644 index 0000000000..fd1a0a6b59 --- /dev/null +++ b/docs/manual/mod/mod_ldap.html @@ -0,0 +1,324 @@ + + + + + + + Apache module mod_ldap + + + + + + + +

Module mod_ldap

+ +
This module is not included with the standard +distribution. It is available via CVS in the http-ldap +module.
+ +

This module adds LDAP connection pooling and result caching + to other Apache LDAP modules (like mod_auth_ldap).

+ +

Status: Extension
+ Source File: util_ldap.c
+ Module Identifier: + ldap_module
+ Compatibility: Available in + Apache 2.0 and later.

+ +

Summary

+ +

This module was created to improve the performance of + websites relying on backend connections to LDAP servers. In + addition to the functions provided by the standard LDAP + libraries, this module adds an LDAP connection pool and an LDAP + shared memory cache.

+ +

To enable this module, LDAP support must be compiled into + apr-util. This is achieved by adding the --with-ldap + flag to the ./configure script when building + Apache.

+ +

Directives

+ + + +

LDAP Connection Pool

+ +

LDAP connections are pooled from request to request. This + allows the LDAP server to remain connected and bound ready for + the next request, without the need to unbind/connect/rebind. + The performance advantages are similar to the effect of HTTP + keepalives.

+ +

On a busy server it is possible that many requests will try + and access the same LDAP server connection simultaneously. + Where an LDAP connection is in use, Apache will create a new + connection alongside the original one. This ensures that the + connection pool does not become a bottleneck.

+ +

There is no need to manually enable connection pooling in + the Apache configuration. Any module using this module for + access to LDAP services will share the connection pool.

+ +

LDAP Cache

+ +

For improved performance, mod_ldap uses an aggressive + caching strategy to minimize the number of times that the LDAP + server must be contacted. Caching can easily double or triple + the throughput of Apache when it is serving pages protected + with mod_auth_ldap. In addition, the load on the LDAP server + will be significantly decreased.

+ +

mod_ldap supports two types of LDAP caching during the + search/bind phase with a search/bind cache and + during the compare phase with two operation + caches. Each LDAP URL that is used by the server has + its own set of these three caches.

+ + +
+ +

LDAPSharedCacheSize + directive

+ +

Syntax: LDAPSharedCacheSize + bytes
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

Specifies the number of bytes to specify for the shared + memory cache. The default is 100kb.

+
+ +

LDAPCacheEntries directive

+ +

Syntax:LDAPCacheEntries + size
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

Specifies the maximum size of the primary LDAP cache. This + cache contains successful search/binds. Set it to 0 to turn off + search/bind caching. The default size is 1024 cached + searches.

+
+ +

LDAPCacheTTL + directive

+ +

Syntax: LDAPCacheTTL + seconds
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

Specifies the time (in seconds) that an item in the + search/bind cache remains valid. The default is 600 seconds (10 + minutes).

+
+ +

LDAPOpCacheEntries directive

+ +

Syntax: LDAPOpCacheEntries + seconds
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

This specifies the number of entries mod_ldap will use to + cache LDAP compare operations. The default is 1024 entries. + Setting it to 0 disables operation caching.

+
+ +

LDAPOpCacheTTL + directive

+ +

Syntax: LDAPOpCacheTTL + seconds
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

Specifies the time (in seconds) that entries in the + operation cache remain valid. The default is 600 seconds.

+
+ +

LDAPCertDBPath + directive

+ +

Syntax: LDAPCertDBPath + directory-path
+ Context: server config
+ Override: Not Applicable
+ Status: Extension
+ Module: mod_ldap

+ +

This directive is only valid if Apache has been linked + against the Netscape/iPlanet Directory SDK.

+ +

It specifies in which directory mod_ldap should look for the + certificate authorities database for SSL support. There should + be a file named cert7.db in that directory.

+ + + +