From b443707c30adf269be67a4020504581a0da9453f Mon Sep 17 00:00:00 2001 From: Bradley Nicholes Date: Fri, 20 Aug 2004 16:12:37 +0000 Subject: [PATCH] Add the documentation for mod_authnz_ldap git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@104743 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/allmodules.xml | 2 +- docs/manual/mod/mod_authnz_ldap.xml | 852 +++++++++++++++++++++++ docs/manual/mod/mod_authnz_ldap.xml.meta | 11 + 3 files changed, 864 insertions(+), 1 deletion(-) create mode 100644 docs/manual/mod/mod_authnz_ldap.xml create mode 100644 docs/manual/mod/mod_authnz_ldap.xml.meta diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml index ea78f5413f..543941e3a6 100644 --- a/docs/manual/mod/allmodules.xml +++ b/docs/manual/mod/allmodules.xml @@ -7,7 +7,7 @@ mod_asis.xml mod_auth_basic.xml mod_auth_digest.xml - mod_auth_ldap.xml + mod_authnz_ldap.xml mod_authn_anon.xml mod_authn_dbm.xml mod_authn_default.xml diff --git a/docs/manual/mod/mod_authnz_ldap.xml b/docs/manual/mod/mod_authnz_ldap.xml new file mode 100644 index 0000000000..95df4d75ea --- /dev/null +++ b/docs/manual/mod/mod_authnz_ldap.xml @@ -0,0 +1,852 @@ + + + + + + + + + +mod_authnz_ldap +Allows an LDAP directory to be used to store the database +for HTTP Basic authentication. +Extension +mod_authnz_ldap.c +authnz_ldap_module +Available in version 2.1 and later + + +

This module provides authentication front-ends such as + mod_auth_basic to authenticate users through + an ldap directory.

+ +

mod_authnz_ldap supports the following features:

+ +
    +
  • Known to support the OpenLDAP SDK (both 1.x + and 2.x), + Novell LDAP SDK and the iPlanet + (Netscape) SDK.
    • + +
  • Complex authorization policies can be implemented by + representing the policy with LDAP filters.
    • + +
  • Uses extensive caching of LDAP operations via mod_ldap.
    • + +
  • Support for LDAP over SSL (requires the Netscape SDK) or + TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).
    • +
+ +

When using mod_auth_basic, this module is invoked + via the AuthBasicProvider + directive with the ldap value.

+ + +mod_ldap +mod_auth_basic +mod_authz_user +mod_authz_groupfile + +
Contents + + +
+ +
Operation + +

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

+ +

mod_authnz_ldap registers both an authn_ldap authentication + provider and an anthz_ldap authorization handler. The authn_ldap + authentication provider can be enabled through the + AuthBasicProvider directive + using the ldap value. The authz_ldap handler extends the + Require directive's authorization types + by adding ldap-user, ldap-dn and ldap-group + values.

+ +
The Authentication + Phase + +

During the authentication phase, mod_authnz_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_authnz_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

+ + + + + + + + + + + + + + + + + + + + +
AuthLDAPURLSpecifies the LDAP server, the + base DN, the attribute to use in the search, as well as the + extra search filter to use.
AuthLDAPBindDNAn optional DN to bind with + during the search phase.
AuthLDAPBindPasswordAn optional password to bind + with during the search phase.
+
+ +
The Authorization Phase + +

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

+ +
    +
  • Grant access if there is a require ldap-user directive, and the + username in the directive matches the username passed by the + client.
    • + +
  • Grant access if there is a require + ldap-dn directive, and the DN in the directive matches + the DN fetched from the LDAP directory.
    • + +
  • Grant access if there is a require ldap-group directive, and + the DN fetched from the LDAP directory (or the username + passed by the client) occurs in the LDAP group.
    • + +
  • otherwise, deny or decline access
    • +
+ +

Other Require values may also be + used which may require loading additional authorization modules.

+ +
    +
  • Grant access if there is a require + valid-user directive. (requires + mod_authz_user)
    • + +
  • Grant access if there is a require group directive, and + mod_authz_groupfile has been loaded with the + AuthGroupFile + directive set.
    • + +
  • others...
    • +
+ + +

mod_authnz_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.
AuthLDAPCompareDNOnServerDetermines the behavior of the + require dn directive.
AuthLDAPGroupAttributeDetermines the attribute to + use for comparisons in the require group + directive.
AuthLDAPGroupAttributeIsDNSpecifies 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. mod_authnz_ldap extends the + authorization types with ldap-user, ldap-dn + and ldap-group. Other authorization types may also be + used but may require that additional authorization modules be loaded.

+ +
require valid-user + +

If this directive exists, mod_authnz_ldap grants + access to any user that has successfully authenticated during the + search/bind phase. Requires that mod_authz_user be + loaded and that the + AuthLDAPAuthoritative + directive be set to off.

+
+ +
require ldap-user + +

The require ldap-user directive specifies what + usernames can access the resource. Once + mod_authnz_ldap has retrieved a unique DN from the + directory, it does an LDAP compare operation using the username + specified in the require ldap-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 surrounded with double quotes. Multiple users can also be + granted access by using multiple require ldap-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 ldap-user "Barbara Jenson"
+require ldap-user "Fred User"
+require ldap-user "Joe Manager"
+ + +

Because of the way that mod_authnz_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 + ldap-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 ldap-user bjenson fuser jmanager +
+ +
require ldap-group + +

This directive specifies an LDAP group whose members are + allowed access. It takes the distinguished name of the LDAP + group. Note: Do not surround the group name with quotes. + 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 ldap-group cn=Administrators, o=Airius + +

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

+
+ +
require ldap-dn + +

The require ldap-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 ldap-dn, then + authorization is granted. Note: do not surround the distinguished + name with quotes.

+ +

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

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

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

+
+
+ +
Examples + +
    +
  • + Grant access to anyone who exists in the LDAP directory, + using their UID for searches. + +AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)
    +require valid-user +     +
    • + +
  • + The next example is the same as above; but with the fields + that have useful defaults omitted. Also, note the use of a + redundant LDAP server. +AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius
    +require valid-user +     +
    • + +
  • + The next example is similar to the previous one, but is + uses the common name instead of the UID. Note that this + could be problematical if multiple people in the directory + share the same cn, because a search on cn + must return exactly one entry. That's why + this approach is not recommended: it's a better idea to + choose an attribute that is guaranteed unique in your + directory, such as uid. + +AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn
    +require valid-user +     +
    • + +
  • + Grant access to anybody in the Administrators group. The + users must authenticate using their UID. + +AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid
    +require ldap-group cn=Administrators, o=Airius +     +
    • + +
  • + The next example assumes that everyone at Airius who + carries an alphanumeric pager will have an LDAP attribute + of qpagePagerID. The example will grant access + only to people (authenticated via their UID) who have + alphanumeric pagers: + +AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)
    +require valid-user +     +
    • + +
  • +

    The next example demonstrates the power of using filters + to accomplish complicated administrative requirements. + Without filters, it would have been necessary to create a + new LDAP group and ensure that the group's members remain + synchronized with the pager users. This becomes trivial + with filters. The goal is to grant access to anyone who has + a filter, plus grant access to Joe Manager, who doesn't + have a pager, but does need to access the same + resource:

    + +AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))
    +require valid-user +     + +

    This last may look confusing at first, so it helps to + evaluate what the search filter will look like based on who + connects, as shown below. The text in blue is the part that + is filled in using the attribute specified in the URL. The + text in red is the part that is filled in using the filter + specified in the URL. The text in green is filled in using + the information that is retrieved from the HTTP client. If + Fred User connects as fuser, the filter would look + like

    + + (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser)) + +

    The above search will only succeed if fuser has a + pager. When Joe Manager connects as jmanager, the + filter looks like

    + + (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager)) + +

    The above search will succeed whether jmanager + has a pager or not.

    +
    • +
+
+ +
Using TLS + +

To use TLS, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

+
+ +
Using SSL + +

To use SSL, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

+ +

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

+
+ +
Using Microsoft + FrontPage with mod_authnz_ldap + +

Normally, FrontPage uses FrontPage-web-specific user/group + files (i.e., the mod_authn_file and + mod_authz_groupfile modules) 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
+AuthGroupFile mygroupfile
+require group mygroupfile
+
 + +

AuthLDAPAuthoritative + must be off to allow mod_authnz_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. 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. By substituting the ldap-group with group file authorization, + Apache is allowed to consult the local user file (which is managed by + FrontPage) - instead of LDAP - when handling authorizing the user.

+ +

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

+
+ +
Caveats + +
    +
  • When choosing the LDAP URL, the attribute to use for + authentication should be something that will also be valid + for putting into a mod_authn_file user file. + The user ID is ideal for this.
    • + +
  • When adding users via FrontPage, FrontPage administrators + should choose usernames that already exist in the LDAP + directory (for obvious reasons). Also, the password that the + administrator enters into the form is ignored, since Apache + will actually be authenticating against the password in the + LDAP database, and not against the password in the local user + file. This could cause confusion for web administrators.
    • + + +
  • Apache must be compiled with mod_auth_basic, + mod_authn_file and + mod_authz_groupfile in order to + use FrontPage support. This is because Apache will still use + the mod_authz_groupfile group file for determine + the extent of a user's access to the FrontPage web.
    • + +
  • The directives must be put in the .htaccess + files. Attempting to put them inside Location or Directory directives won't work. This + is because mod_authnz_ldap has to be able to grab + the AuthGroupFile + directive that is found in FrontPage .htaccess + files so that it knows where to look for the valid user list. If + the mod_authnz_ldap directives aren't in the same + .htaccess file as the FrontPage directives, then + the hack won't work, because mod_authnz_ldap will + never get a chance to process the .htaccess file, + and won't be able to find the FrontPage-managed user file.
    • +
+
+
+ + +AuthLDAPAuthoritative +Prevent other authentication modules from +authenticating the user if this one fails +AuthLDAPAuthoritative on|off +AuthLDAPAuthoritative on +directory.htaccess + +AuthConfig + + +

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 +Optional DN to use in binding to the LDAP server +AuthLDAPBindDN distinguished-name +directory.htaccess + +AuthConfig + + +

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

+ + + + +AuthLDAPBindPassword +Password used in conjuction with the bind DN +AuthLDAPBindPassword password +directory.htaccess + +AuthConfig + + +

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.

+ + + + +AuthLDAPCharsetConfig +Language to charset conversion configuration file +AuthLDAPCharsetConfig file-path +server config + + + +

The AuthLDAPCharsetConfig directive sets the location + of the language to charset conversion configuration file. File-path is relative + to the ServerRoot. This file specifies + the list of language extensions to character sets. + Most administrators use the provided charset.conv + file, which associates common language extensions to character sets.

+ +

The file contains lines in the following format:

+ + + Language-Extension charset [Language-String] ... + + +

The case of the extension does not matter. Blank lines, and lines + beginning with a hash character (#) are ignored.

+ + + + +AuthLDAPCompareDNOnServer +Use the LDAP server to compare the DNs +AuthLDAPCompareDNOnServer on|off +AuthLDAPCompareDNOnServer on +directory.htaccess + +AuthConfig + + +

When set, mod_authnz_ldap will use the LDAP + server to compare the DNs. This is the only foolproof way to + compare DNs. mod_authnz_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_authnz_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 +When will the module de-reference aliases +AuthLDAPDereferenceAliases never|searching|finding|always +AuthLDAPDereferenceAliases Always +directory.htaccess + +AuthConfig + + +

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

+ + + + +AuthLDAPGroupAttribute +LDAP attributes used to check for group membership +AuthLDAPGroupAttribute attribute +directory.htaccess + +AuthConfig + + +

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_authnz_ldap uses the member and + uniquemember attributes.

+ + + + +AuthLDAPGroupAttributeIsDN +Use the DN of the client username when checking for +group membership +AuthLDAPGroupAttributeIsDN on|off +AuthLDAPGroupAttributeIsDN on +directory.htaccess + +AuthConfig + + +

When set on, 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_authnz_ldap will check if the group has + cn=Babs Jenson, o=Airius as a member. If this + directive is not set, then mod_authnz_ldap will + check if the group has bjenson as a member.

+ + + + +AuthLDAPRemoteUserIsDN +Use the DN of the client username to set the REMOTE_USER +environment variable +AuthLDAPRemoteUserIsDN on|off +AuthLDAPRemoteUserIsDN off +directory.htaccess + +AuthConfig + + +

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.

+ + + + +AuthLDAPUrl +URL specifying the LDAP search parameters +AuthLDAPUrl url +directory.htaccess + +AuthConfig + + +

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 + +
+
ldap
+ +
For 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_authnz_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_authnz_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.

+
+ +
basedn
+ +
The 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.
+ +
attribute
+ +
The 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.
+ +
scope
+ +
The 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.
+ +
filter
+ +
A 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_authnz_ldap.xml.meta b/docs/manual/mod/mod_authnz_ldap.xml.meta new file mode 100644 index 0000000000..d63d25c3c1 --- /dev/null +++ b/docs/manual/mod/mod_authnz_ldap.xml.meta @@ -0,0 +1,11 @@ + + + + mod_authnz_ldap + /mod/ + .. + + + en + + -- 2.50.1