LDAP Authentication Prior to EZproxy 4.0

Minimum version required

The options described in this document require EZproxy 3.0a GA (2004-08-02) through EZproxy 3.6.

LDAP was configured quite differently in older version of EZproxy. See Older LDAP Authentication for configuration information for older versions.

EDUCAUSE/Internet2 eduPerson LDAP object class

If your institution has not had a chance to review the EDUCAUSE/Internet2 eduPerson LDAP object class, OCLC would suggest you take a moment to review it at www.educause.edu/eduperson to consider the potential benefits. The use of multi-valued attributes such as eduPersonAffiliation and eduPersonScopedAffiliation as a method to deal mapping combinations of faculty, staff, students, alumni, etc., is quite powerful in its ability to be leveraged across many applications including EZproxy.

Test LDAP

Your server's EZproxy Administration has a link titled "Test LDAP". This tool can be used to build your initial LDAP configuration. To use this tool with Active Directory, see LDAP Authentication with Active Directory for additional information.

Directives

LDAP authentication is configured by making entries in the user.txt/ezproxy.usr file. An LDAP entry in user.txt/ezproxy.usr takes this general form:

::LDAP
LDAPDirective
LDAPDirective
/LDAP

The directives for LDAP may be divided into two groups: conditions and actions.

Conditions indicate tests that must be true if the current line is to be considered further. At the end of a condition, insert a semi-colon (;), then include another condition or one or more actions.

Actions direct EZproxy to perform specific tasks. Multiple actions may appear on the same line separated by semi-colons (;).

Directives whose descriptions start with [RARE] are provided for highly unusual configurations and will not be used by most users.

Conditions

These are the conditions available and what they test:

Member LDAPGroupDN

Tests whether or not the user is a member of the specified LDAP group.

NoGroups

True if the user is not a member of any EZproxy groups.

Refused

True if EZproxy was unable to contact the LDAP server (but not true if EZproxy was able to contact the server but the servers refused the username and password provided).

Test LDAPAttribute Value

True if the user has the specified LDAPAttribute with the specified Value.

Test -wild LDAPAttribute Value

Introduced in EZproxy 3.0f (2004-10-26), this variant form of Test allows you to specific the Value using the * wildcard to match 0 or more characters.

Actions

These are the actions available:

Allow

Allow the remote user to have access. Once an allow is encountered, either directly or as part of a condition, the rest of LDAP processing stops and the user is granted access.

BindPassword password

Specifies the password to use when binding to the directory to search for the user. If provided, must appear before URL.

BindUser user

Specifies the distinguished name (DN) to use when binding to the directory to search for the user. If provided, must appear before URL.

Deny [filename]

Deny access to the remote user. May be followed by a filename, for which EZproxy will look in the docs subdirectory. If the filename is omitted, EZproxy sends the file deny.htm. The rest of the LDAP options are ignored.

DisableReferralChasing

Directs EZproxy to specify its LDAP search in a slightly different manner. The only instance in which this directive needs to be specified occurs when searching Active Directory from the root entrty and you receive the error "Operations Error." In this instance, add DisableReferralChasing before your URL line. This directive first appeared in EZproxy 3.2.

Group [+|-]GroupName[[+|-]GroupName]

Specifies EZproxy groups to which the user should be given access or denied access. The special GroupName NULL may be specified to place the user in no groups at all.

LDAPV2

[RARE] By default, EZproxy uses LDAP Version 3 when connecting. If your server supports only LDAP Version 2, add this directive before your URL directive.

MemberAttribute Attribute

[RARE] EZproxy normally checks group membership by looking for the member or uniqueMember attribute. If your LDAP server uses a different attribute, use this directive to indicate the attribute to check. This directive should appear before the Member directive.

MemberUser

[RARE] By default, EZproxy checks LDAP group membership using the LDAP distinguished name. If your LDAP server stores group membership by just the name component that people will type in as their username, specify this directive. This directive should appear before the Member directive.

TestWithBind

[RARE] Introduced in EZproxy 3.0e (2004-09-19), this directive tells EZproxy to perform the Member and Test checks using its original connection to the LDAP server. This is the default behavior. See TestWithUser for more information.

TestWithUser

[RARE] Introduced in EZproxy 3.0e (2004-09-19), this directive tells EZproxy to perform Member and Test checks using the connection established to the LDAP server when the user's password was checked. This is useful in instances where you use anonymous bind or when your BindUser does not have the rights to access the attributes used for a test.

URL LDAPURL

This directive is always required. The LDAP URL to use to determine how to connect to and search the LDAP server. The URL takes this form:

ldap[s]:// host[: port]/ [root]? attribute? scope? filter

The URL starts with either ldap for normal LDAP or ldaps for secure LDAP using SSL. host is the hostname of the LDAP server, which may be followed by an colon and optional port number. root is the root from which searching should occur. attribute is the LDAP attribute that should be used to find the user and is most commonly specified as uid, cn, or sAMAccountName. scope can be one (search only at the root location) or sub (search starting at the root location and the entire subtree below the specified root). filter is an LDAP filter to apply to the search such as (objectClass=person) to search for user objects only.

Search using anonymous access using uid

This example

::LDAP
URL ldap://ldap.yourlib.org/?uid?sub?(objectClass=person)
Unauthenticated; Stop
/LDAP


Searching using authenticated access using sAMAccountName (Windows username)

::LDAP
BindUser CN=ezproxy,CN=users,DC=yourlib,DC=org
BindPassword verysecret
URL ldap://ldapserv.yourlib.org/CN=users,DC=yourlib,DC=org?sAMAccountName?sub?(objectClass=person)
/LDAP


Limit access to users who have a specific attribute value

This example checks the user to see if the user has an attribute named eduPersonAffiliation with the value of student, faculty, employee, or staff, and if so, allows access. If the user has this attribute with a value of alum, EZproxy looks for the file alum.html in the docs subdirectory and sends that to the user, then denies access. If the user does not have this attribute or if the user has this attribute but with none of these values, EZproxy looks for the file other.html in the docs subdirectory and sends that to the user, then denies access.

::LDAP
URL ldap://ldapserv.yourlib.org/DC=yourlib,DC=org?uid?sub?(objectClass=person)
Unauthenticated; Stop
Test eduPersonAffiliation student; Stop
Test eduPersonAffiliation faculty; Stop
Test eduPersonAffiliation employee; Stop
Test eduPersonAffiliation staff; Stop
Test eduPersonAffiliation alum; Deny alum.html
Deny other.html
/LDAP


Alter EZproxy group membership based on LDAP group membership

In this example, all authenticated users are placed in the EZproxy General group, and those users who are members of the LDAP CN=Law,CN=Users,DC=yourlib,DC=org group are also placed in the EZproxy Legal group.

::LDAP
BindUser CN=ezproxy,CN=users,DC=yourlib,DC=org
BindPassword verysecret
URL ldap://ldapserv.yourlib.org/CN=users,DC=yourlib,DC=org?sAMAccountName?sub?(objectClass=person)
Unauthenticated; Stop
Group General
Member CN=Law,CN=Users,DC=yourlib,DC=org; Group +Legal
/LDAP


Novell example

Novell stores group memberships as attributes, so this example demonstrates checking LDAP group membership using Test with the groupMembership attribute.

::LDAP
URL ldaps://ldapserv.yourlib.org/OU=users,O=yourlib?uid?sub?(objectClass=person)
Unauthenticated; Stop
Group General
Test groupMembership CN=Health,OU=users,O=yourlib; Group +Medical
/LDAP


Extended characters in usernames or password

If your usernames or passwords contain extended characters (e.g., ä, ñ, ó), you will need to edit login.htm and loginbu.htm in the docs directory and add:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">


immedaitely following the <head> tag to insure that these characters are encoded properly for authentication against LDAP.