Apache Module mod_authnz_ldap

This module allows authentication front-ends such as

to authenticate users through an ldap directory.modauthbasic

supports the following features:modauthnzldap

determines if the authenticated user is allowed access to the resource in question. This is also known as the modauthnzldapcompare phase.

registers both an authnldap authentication provider and an authzldap authorization handler. The authnldap authentication provider can be enabled through the modauthnz_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 modauthnzldap

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.modauthnzldap

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

attempts to determine if the user is authorized to access the resource. Many of these checks require modauthnzldap

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

has been loaded with the AuthGroupFile

| The attribute specified in the URL is used in compare operations for the Require ldap-user operation. | | Determines the behavior of the Require ldap-dn directive. | | Determines the attribute to use for comparisons in the Require ldap-group directive. | | Specifies whether to use the user DN or the username when doing comparisons for the Require ldap-group directive. | | Determines the maximum depth of sub-groups that will be evaluated during comparisons in the Require ldap-group directive. | | Determines the attribute to use when obtaining sub-group members of the current group during comparisons in the Require ldap-group directive. | | Specifies the LDAP objectClass values used to identify if queried directory objects really are group objects (as opposed to user objects) during the Require ldap-group directive's sub-group processing. |

Since v2.4.8, expressions are supported within the LDAP require directives.

directive specifies what usernames can access the resource. Once

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

Require ldap-user "Barbara Jenson" Require ldap-user "Fred User" Require ldap-user "Joe Manager"

handles this directive, Barbara Jenson could sign on as modauthnzldapBarbara Jenson, Babs Jenson or any other cn

attribute in the URL above, the above three lines could be condensed to

Require ldap-user bjenson fuser jmanager

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:

is set to a value greater than 0. For example, assume the following entries exist in the LDAP directory:AuthLDAPMaxSubGroupDepth

dn: cn=Employees, o=Example objectClass: groupOfUniqueNames uniqueMember: cn=Managers, o=Example uniqueMember: cn=Administrators, o=Example uniqueMember: cn=Users, o=Example dn: cn=Managers, o=Example objectClass: groupOfUniqueNames uniqueMember: cn=Bob Ellis, o=Example uniqueMember: cn=Tom Jackson, o=Example dn: cn=Administrators, o=Example objectClass: groupOfUniqueNames uniqueMember: cn=Barbara Jenson, o=Example uniqueMember: cn=Fred User, o=Example dn: cn=Users, o=Example objectClass: groupOfUniqueNames uniqueMember: cn=Allan Jefferson, o=Example uniqueMember: cn=Paul Tilley, o=Example uniqueMember: cn=Temporary Employees, o=Example dn: cn=Temporary Employees, o=Example objectClass: groupOfUniqueNames uniqueMember: cn=Jim Swenson, o=Example uniqueMember: cn=Elliot Rhodes, o=Example

The following directives would allow access for Bob Ellis, Tom Jackson, Barbara Jensen, Fred User, Allan Jefferson, and Paul Tilley but would not allow access for Jim Swenson, or Elliot Rhodes (since they are at a sub-group depth of 2):

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

The following directive would grant access to anyone with the attribute employeeType = active

directives. The effect of listing multiple attribute/values pairs is an OR operation. Access will be granted if any of the listed attribute values match the value of the corresponding attribute in the user object. If the value of the attribute contains a space, only the value must be within double quotes.

The following directive would grant access to anyone with the city attribute equal to "San Jose" or status equal to "Active"

directive allows the administrator to grant access based on a complex LDAP search filter. If the dn returned by the filter search matches the authenticated user dn, access is granted.

The following directive would grant access to anyone having a cell phone and is in the marketing department

performs a search operation on the LDAP directory using the specified search filter rather than a simple attribute comparison. If a simple attribute comparison is all that is required, the comparison operation performed by ldap-attribute

especially within a large directory.

AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)" Require valid-user

. The example will grant access only to people (authenticated via their UID) who have alphanumeric pagers: AuthLDAPURL ldap://ldap.example.com/o=Example?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 pager, plus grant access to Joe Manager, who doesn't have a pager, but does need to access the same resource:

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. If Fred User connects as fuser

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

to override the default connection type set by AuthLDAPURL

. This will allow the connection established by an LDAPTrustedModeldap:// Url to be upgraded to a secure connection on the same port.

To specify a secure LDAP server, use ldaps:// in the

If the attribute field contains the username, common name and telephone number of a user, a CGI program will have access to this information without the need to make a second independent LDAP query to gather this additional information.

This has the potential to dramatically simplify the coding and configuration required in some web applications.

An Active Directory installation may support multiple domains at the same time. To distinguish users between domains, an identifier called a User Principle Name (UPN) can be added to a user's entry in the directory. This UPN usually takes the form of the user's account name, followed by the domain components of the particular domain, for example somebody@nz.example.com.

You may wish to configure the

module to authenticate users present in any of the domains making up the Active Directory forest. In this way both modauthnzldapsomebody@nz.example.com and someone@au.example.com can be authenticated using the same query at the same time.

To make this practical, Active Directory supports the concept of a Global Catalog. This Global Catalog is a read only copy of selected attributes of all the Active Directory servers within the Active Directory forest. Querying the Global Catalog allows all the domains to be queried in a single query, without the query spanning servers over potentially slow links.

If enabled, the Global Catalog is an independent directory server that runs on port 3268 (3269 for SSL). To search for a user, do a subtree search for the attribute userPrincipalName, with an empty search root, like so:

Users will need to enter their User Principal Name as a login, in the form somebody@nz.example.com.

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 modauthzgroupfilePermissions 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

AuthLDAPURL "the url" AuthGroupFile mygroupfile Require group mygroupfile

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.

in order to use FrontPage support. This is because Apache will still use the modauthzgroupfile

files. Attempting to put them inside

file as the FrontPage directives, then the hack won't work, because modauthnzldap

will never get a chance to process the .htaccess

is set to AuthLDAPBindAuthoritativeoff, other configured authentication modules will have a chance to validate the user if the LDAP bind (with the current user's credentials) fails for any reason.

to authenticate when the LDAP server is available but the user's account is locked or password is otherwise unusable.AuthUserFile

If the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the password.

#Password used as-is AuthLDAPBindPassword secret #Run /path/to/program to get my password AuthLDAPBindPassword exec:/path/to/program #Run /path/to/otherProgram and provide arguments AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"

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

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

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. | |---|

If the verbatim username can't directly bind, but needs some cosmetic transformation, see

The regular expression argument is compared against the current basic authentication username. The substitution argument may contain backreferences, but has no other variable interpolation.

AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com

See the Require ldap-group section for a more detailed example.

(as it does by default and as required by common LDAP schemas), uncached searching for subgroups in large groups can be very slow. If you use large, non-nested groups, set AuthLDAPMaxSubGroupDepth

environment variable will be set to the value of the attribute specified. Make sure that this attribute is included in the list of attributes in the AuthLDAPUrl definition, otherwise this directive will have no effect. This directive, if present, takes precedence over AuthLDAPRemoteUserIsDN. This directive is useful should you want people to log into a website using an email address, but a backend application expects the username as a userid.

directive specifies the LDAP objectClass values used in verifying that these potential sub-groups are in fact group objects. Verified sub-groups can then be searched for more user or sub-group members. Multiple attributes can be used by specifying this directive multiple times. If not specified, then

AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS]

ldap://host:port/basedn?attribute?scope?filter

Caveat: If you specify multiple servers, you need to enclose the entire URL string in quotes; otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." You can of course use search parameters on each of these.

instead. Secure LDAP is only available if Apache was linked to an LDAP library with SSL support.The name/port of the ldap server (defaults to localhost:389

will try connecting to each server in turn, until it makes a successful connection. If multiple ldap servers are specified, then entire LDAP URL must be encapsulated in double quotes.modauthnzldap

Once a connection has been made to a server, that connection remains active for the life of the

If the LDAP server goes down and breaks an existing connection,

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.modauthnzldap

. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using. All attributes listed will be put into the environment with an AUTHENTICATE_ prefix for use by other modules.one

, which will search for all objects in the tree. Filters are limited to approximately 8000 characters (the definition of MAXSTRINGLEN

in the Apache source code). This should be more than sufficient for any application. In 2.4.10 and later, The word "none" may be used to not use any filter, which may be required by some primitive LDAP servers.When doing searches, the attribute, filter and username passed by the HTTP client are combined to create a search filter that looks like (&(

For example, consider an URL of ldap://ldap.example.com/o=Example?cn?sub?(posixid=*)

An optional parameter can be added to allow the LDAP Url to override the connection type. This parameter can be one of the following:

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.4