Apache Module mod_webauthldap

Available Languages: en

Description:	LDAP authorization and lookup for WebAuth V3
Status:
Module Identifier:	webauthldap_module
Source File:	mod_webauthldap.c

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 SASL GSSAPI Kerberos 5.

For other WebAuth documentation see the WebAuth documentation.

Topics

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

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 priviledgeAttribute
WebAuthLdapKeytab conf/webauth/ldapkeytab webauth/myservername
WebAuthLdapTktCache /tmp/webauthldap.tkt

Using WebAuthLdap Authorization

To restrict access to particular priviledge 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.

Example

<Location /private/>
  AuthType WebAuth
  Require valid-user
  WebAuthLdapAttribute displayName
  WebAuthLdapAttribute description
  WebAuthLdapAttribute telephoneNumber
</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 and SU_AUTH_DIRMAIL variables set, you need to use the new WebAuthLdapAttribute directives explicitly. If you dont 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 down.

With Name and Mail variables:

<Location /top/>
  WebAuthLdapAttribute mail
  WebAuthLdapAttribute displayName
</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.

WebAuthLdapAttribute Directive

Description:	LDAP attribute to place in the environment
Syntax:	`WebAuthLdapAttribute ldap_attribute_name`
Default:	`"displayName", "mail"`
Context:	directory
Status:
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. Only one attribute may be listed per directive, but multiple directives can be used.

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.

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:
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 priviledgeAttribute

WebAuthLdapAuthrule Directive

Description:	Whether to show authorization information
Syntax:	`WebAuthLdapAuthrule on\|off`
Default:	`on`
Context:	server config, virtual host
Status:
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 "group 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:
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:
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:
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:
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:
Module:	mod_webauthldap

The LDAP server must support SASL GSSAPI Kerberos V 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:
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.

Example

WebAuthLdapKeytab conf/webauth/ldapkeytab webauth/myservername

WebAuthLdapPort Directive

Description:	LDAP server port
Syntax:	`WebAuthLdapPort port_num`
Default:	`389`
Context:	server config, virtual host
Status:
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

WebAuthLdapSeparator Directive

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

If set, overrides the default handling of multi-valued attributes. 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. Nothing special will be done to any occurrances 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:
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:
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