Apache HTTP Server Version 2.5

Apache > HTTP Server > Documentation > Version 2.5 > Modules

# Apache Module mod_webauthldap

Available Languages: en

Description: | LDAP authorization and lookup for WebAuth
Status: | External
Module Identifier: | webauthldap_module
Source File: | mod_webauthldap.c
Compatibility: | Apache 2.0 and higher

### Summary

This module provides authorization based on configurable LDAP privilege groups. It also allows retrieving adhoc LDAP attributes and places them in environment variables. The module was designed for use with an LDAP server that supports LDAP version 3 and allows binds authenticated using GSS-API Kerberos via SASL.

For other WebAuth documentation see the WebAuth documentation.

### Directives

### Topics

- Generic Minimal Config File
- Using WebAuthLdap Authorization
- Ad hoc attributes lookup
- WebAuth 2.x backward compatibility
- Manual License

## Generic Minimal Config File

The following example shows the minimum config file required to configure this module.

### Example

    LoadModule webauthldap_module modules/mod_webauthldap.so

    WebAuthLdapHost ldap.acme.com
    WebAuthLdapBase dc=acme,dc=com
    WebAuthLdapAuthorizationAttribute privilegeAttribute
    WebAuthLdapKeytab conf/webauth/ldapkeytab webauth/myservername
    WebAuthLdapTktCache /tmp/webauthldap.tkt

## Using WebAuthLdap Authorization

To restrict access to particular privilege group(s) place the `require privgroup <group name>` directives in a .htaccess file, a Location block or a Directory block where `AuthType WebAuth` has already been applied. Multiple directives mean "user must belong to at least one of these groups." There is currently no way to require that a user be in multiple groups.

When combining with other require directives, the order of checking is top to bottom, so e.g. by placing `require valid-user` at the top, all authenticated users will be authorized no matter what group restrictions are below it. By default, if a user is authorized, the WEBAUTH_LDAPAUTHRULE variable will be set to indicate what rule succeded in authorizing a user.

It is possible to combine `Require privgroup` with Apache's regular `Require group`. In this case if no LDAP group matches, the regular auth groups can be checked by apache in the usual manner, and access granted if the user is in them. However when using WebAuthLdap the AuthAuthoritative directive must be set to off, otherwise mod_access will logs messages complaining that it doesn't recognize the `Require privgroup` directives.

### Example

    <Location /private/>
      AuthType WebAuth
      Require privgroup stanford:staff
      Require privgroup stanford:faculty
    </Location>

## Ad hoc attributes lookup

By using the WebAuthLdapAttribute directive in a .htaccess file, a Location block or a Directory block, any attributes available to the WebAuth server can be set into environment variables for use in cgi scripts. In case the requested attribute is not available from the LDAP server, there is no error and the environment variable is simply not set for that attribute.

The name of the environment variable is formed by prepending WEBAUTH_LDAP_ to the uppercased attribute name. In the case of mulivalued attributes, the WEBAUTH_LDAP_ATTRIBUTENAME variable will contain one value randomly picked from the set, and all the values of this attribute will also be set into WEBAUTH_LDAP_ATTRIBUTENAME1, WEBAUTH_LDAP_ATTRIBUTENAME2, and so on, in no particular order. The multivalued attribute behavior can be changed by setting the WebAuthLdapSeparator directive, in which case WEBAUTH_LDAP_ATTRIBUTENAME will be set to the concatenation of all returned values, separated by that separator.

The WebAuthLdapPrivgroup directive is also available to test a user's membership in an authorization group, while still allowing users who are not members of that group to access a resource. If the user is a member of the group, the group's name is set in the environment variable WEBAUTH_LDAPPRIVGROUP. As with attributes, if the user is found to be a member of multiple groups, those group names are stored in variables named WEBAUTH_LDAPPRIVGROUP1, WEBAUTH_LDAPPRIVGROUP2 and so on, with one of the groups, picked at random, in the usual WEBAUTH_LDAPPRIVGROUP variable -- unless WebAuthLdapSeparator is set, in which case WEBAUTH_LDAPPRIVGROUP contains the concatenation of all those groups, separated by that separator.

### Example

    <Location /private/>
      AuthType WebAuth
      Require valid-user
      WebAuthLdapAttribute displayName
      WebAuthLdapAttribute description
      WebAuthLdapAttribute telephoneNumber
      WebAuthLdapPrivgroup stanford:faculty
      WebAuthLdapPrivgroup stanford:student
    </Location>

## WebAuth 2.x backward compatibility

StanfordAuth as an AuthType is supported as a form of backward compatibility, to ease the transition from WebAuth v2. When it is used, require group directives are interpreted as checks on LDAP privgroups if they contain a colon.

### StanfordAuth Example

    <Location /private/>
      AuthType StanfordAuth
      require group stanford:stanford
    </Location>

If you wish to have the legacy SU_AUTH_DIRNAME, SU_AUTH_DIRMAIL, or SU_AUTH_UNIVID variables set, you need to use the new WebAuthLdapAttribute directives explicitly. If you don't want to go through and change numerous .htaccess files, you can set the WebAuthLdapAttribute directive on some top location above all the .htaccess files, and they wil be inherited.

### With name, mail, and univid variables:

    <Location /top/>
      WebAuthLdapAttribute mail
      WebAuthLdapAttribute displayName
      WebAuthLdapAttribute suUnivid
    </Location>

    # .htaccess file in /top/mydir can remain like this:
    AuthType StanfordAuth
    require group stanford:stanford

This backward compatibility support is probably of interest only to Stanford users, since WebAuth v2 was never publically released.

## Manual License

Copyright 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012, 2014 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

## WebAuthLdapAttribute Directive

Description: | LDAP attribute to place in the environment
Syntax: | `WebAuthLdapAttribute attribute [attribute] ...`
Default: | `"displayName", "mail"`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | External
Module: | mod_webauthldap

All attributes indicated by this directive will be looked up in LDAP and their values, if found, will be placed into the environment. This directive can be used multiple times.

The name of the environment variable is formed by prepending WEBAUTH_LDAP_ to the uppercased attribute name. By default, in the case of mulivalued attributes, the WEBAUTH_LDAP_ATTRIBUTENAME variable will contain one value randomly picked from the set, and all the values of this attribute will also be set into WEBAUTH_LDAP_ATTRIBUTENAME1, WEBAUTH_LDAP_ATTRIBUTENAME2, and so on, in no particular order. To override this behavior, see WebAuthLdapSeparator.

The attributes can be any attribute found in your LDAP server that the server using this module has access to read, except for operational attributes, like entryUUID.

### Example

`<Location /private/>
AuthType WebAuth
Require privgroup stanford:staff
WebAuthLdapAttribute suAffiliation
WebAuthLdapAttribute displayName
WebAuthLdapAttribute suUnivid
</Location>
`

## WebAuthLdapAuthorizationAttribute Directive

Description: | LDAP attribute for authorization group membership
Syntax: | `WebAuthLdapAuthorizationAttribute ldap_attribute_name`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

Specifies the attribute in the LDAP directory in a user's entry that contains the authorization groups that user is a member of. This should be a multi-valued attribute against with LDAP compare operations are performed. Each privgroup granted access to the URL being accessed will be compared in turn against the values of this attribute and the user will be granted access only if one of those privgroups match.

Note that this module does not use LDAP groups for authorization and instead uses this multivalued attribute method. Proper use of LDAP groups may be added later.

### Note

This directive must be set.

### Example

`WebAuthLdapAuthorizationAttribute privilegeAttribute`

## WebAuthLdapAuthrule Directive

Description: | Whether to show authorization information
Syntax: | `WebAuthLdapAuthrule on|off`
Default: | `on`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

By default, this module will put the authorization rule under which the user was authorized into the WEBAUTH_LDAPAUTHRULE environment variable. The value will be one of "valid-user", "user user", or "privgroup privgroup". You can disable this behavior by setting this directive to off.

### Example

`WebAuthLdapAuthrule off`

## WebAuthLdapBase Directive

Description: | Base for the LDAP lookup
Syntax: | `WebAuthLdapBase valid_search_base`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

The lookup of the user's entry will begin at the specified search base.

### Note

This directive must be set.

### Example

`WebAuthLdapBase cn=people,dc=acme,dc=com`

## WebAuthLdapBindDN Directive

Description: | Bind DN for the LDAP lookup
Syntax: | `WebAuthLdapBindDN valid_bind_dn`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

The bind DN specifies the LDAP identity that this module will use when binding to the LDAP server. Most OpenLDAP servers do not need an explicit bind DN and determine the binding identity from the authentication credentials, so this normally will not have to be set.

### Example

`WebAuthLdapBindDN cn=myDN,dc=acme,dc=com`

## WebAuthLdapDebug Directive

Description: | Set the debugging level for logging
Syntax: | `WebAuthLdapDebug on|off`
Default: | `off`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

If set to on, additional tracing and debugging output will be sent to the server log. This output will include the stages of processing, the LDAP parameters used, and the returned results. It's rather verbose, so should probably only be enabled during debugging.

### Example

`WebAuthLdapDebug on`

## WebAuthLdapFilter Directive

Description: | LDAP filter to use when searching for an entry
Syntax: | `WebAuthLdapFilter valid_ldap_filter`
Default: | `uid=USER`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

This can be any properly formed LDAP filter. The current user's identity (from WebAuth) will be substituted for the upper-cased string "USER". The "USER" string may appear in the filter multiple times. You will want to set this attribute if your LDAP server puts the username in an attribute other than uid, or if you want to add additional restrictions to the search.

### Example

`WebAuthLdapFilter (&(objectClass=superson)(uid=USER))`

## WebAuthLdapHost Directive

Description: | Hostname of the LDAP server
Syntax: | `WebAuthLdapHost hostname`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

The LDAP server must support GSS-API Kerberos SASL binds. No other bind type is supported by mod_webauthldap at this time.

### Note

This directive must be set.

### Example

`WebAuthLdapHost ldap.acme.com`

## WebAuthLdapKeytab Directive

Description: | Keytab for LDAP server authentication
Syntax: | `WebAuthLdapKeytab path [principal]`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

Specifies the keytab used for GSSAPI authentication to the LDAP server. This keytab should contain an entry for the principal that has access to the desired LDAP attributes. If the keytab contains several principals, use the optional second argument to this directive to indicate the principal to use.

If the path is not absolute, it will be treated as being relative to `ServerRoot`.

### Note

This directive must be set. While it is permitted in either the main server configuration or in a virtual host configuration, it should be set once and only once for the whole server. The module currently does not support having separate authentication configurations in different virtual hosts.

### Example

`WebAuthLdapKeytab conf/webauth/ldapkeytab webauth/myservername`

## WebAuthLdapOperationalAttribute Directive

Description: | LDAP operational attribute to place in the environment
Syntax: | `WebAuthLdapOperationalAttributeoper_attribute [oper_attribute] ...`
Default: | `none`
Context: | directory, .htaccess
Status: | External
Module: | mod_webauthldap

All attributes defined by this directive will be looked up additionally and their values will be inserted into the environment. This directive can also be used multiple times.

LikeWebAuthLdapAttribute, the name of the enviornment variable is formed by prepending WEBAUTH_LDAP_ to the uppercased name. Multivalued attributes work exactly the same as well.

### Example

`<Location /private/>
AuthType WebAuth
Require privgroup stanford:staff
WebAuthLdapOperationalAttribute entryUUID
</Location>
`

## WebAuthLdapPort Directive

Description: | LDAP server port
Syntax: | `WebAuthLdapPort port_num`
Default: | `389`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

Normally, you will never need to change this, even if using SSL. Some LDAP servers may require SSL connections on port 636 (but this is a deprecated configuration).

### Example

`WebAuthLdapPort 389`

## WebAuthLdapPrivgroup Directive

Description: | Authorization group in which to test user's membership
Syntax: | `WebAuthLdapPrivgroup privgroup [privgroup] ...`
Default: | `none`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | External
Module: | mod_webauthldap

The user's membership will be tested in the authorization group specified with this directive. If the user is a member of the group, the name of the group is placed in the environment variable WEBAUTH_LDAPPRIVGROUP.

This directive can be used multiple times. If the user is found to be a member of multiple groups, the WEBAUTH_LDAPPRIVGROUP variable will contain the name of one group, selected at random, and the names of all the groups will be stored in the variables WEBAUTH_LDAPPRIVGROUP1, WEBAUTH_LDAPPRIVGROUP2, and so on, in no particular order. To override this behavior, see WebAuthLdapSeparator.

(Also see the WebAuthLdapAuthorizationAttribute directive for a caveat about how authorization groups must be defined in LDAP.)

### Example

`<Location /webapp/>
AuthType WebAuth
Require valid-user
WebAuthLdapPrivgroup stanford:staff
WebAuthLdapPrivgroup stanford:faculty stanford:student
</Location>
`

## WebAuthLdapSeparator Directive

Description: | Separator for multi-valued attributes and privgroups
Syntax: | `WebAuthLdapSeparator separator`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

If set, overrides the default handling of multi-valued attributes and privgroups. Normally, one value chosen at random will go into the base WEBAUTH_LDAP_ATTRIBUTE environment variable and then all of the attributes will go into separate environment variables formed by appending a number to that basic name. When this attribute is set, the individual numbered variables will still be set, but the unnumbered WEBAUTH_LDAP_ATTRIBUTE variable will be set to the concatenation of all of the values found, separated by the given separator string.

Similarly, if multiple authorization groups are tested with WebAuthLdapPrivgroup, one of the user's groups is normally chosen at random to go into the variable WEBAUTH_LDAPPRIVGROUP. When a separator is specified, the numbered variables WEBAUTH_LDAPPRIVGROUP1, WEBAUTH_LDAPPRIVGROUP2, and so on are still set, but the base variable WEBAUTH_LDAPPRIVGROUP will be set to the concatention of all the user's verified groups, separated by the specified string.

In all cases, nothing special will be done to any occurrences of the separator string in the values, so pick a separator that doesn't occur in the values you're working with.

### Example

`WebAuthLdapSeparator |`

## WebAuthLdapSSL Directive

Description: | Whether to use SSL with LDAP connections
Syntax: | `WebAuthLdapSSL on|off`
Default: | `off`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

If set, this module will use SSL when talking to the LDAP server. The LDAP server must support SSL or LDAP connections will fail. This will slow LDAP lookups and incur more load on the server and client, and GSSAPI normally already encrypts the session, so setting this option is rarely needed.

### Example

`WebAuthLdapSSL on`

## WebAuthLdapTktCache Directive

Description: | Path to the Kerberos credentials cache file
Syntax: | `WebAuthLdapTktCache path`
Default: | `none`
Context: | server config, virtual host
Status: | External
Module: | mod_webauthldap

If this cache exists and is valid and readable, it will be used until it expires. After expiration, or if it doesn't exist, the specified keytab will be used to obtain a new ticket which is stored in this cache.

If the path is not absolute, it will be treated as being relative to `ServerRoot`.

### Note

This directive must be set.

### Example

`WebAuthLdapTktCache /tmp/webauthldap.tkt`

Available Languages: en