Skip to page content

LDAP Authentication

Version requirement

These instructions are only accurate for EZproxy 4.0 or later. Users of earlier versions of EZproxy should consult LDAP Authentication Prior to EZproxy 4.0 .

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.

Conditions and Actions

LDAP authentication is controlled by a series of conditions and actions. Conditions are tests that must be true if the current line is to be considered further. The LDAP specific conditions are IfMember, IfRefused, and IfTest. Actions are things that EZproxy should do. The LDAP specific actions are BindPassword, BindUser, DisableReferralChasing, LDAPV2, MemberAttribute, MemberUser, TestWithBind, TestWithUser, and URL. Actions whose descriptions start with [RARE] are provided for highly unusual configurations and will not be used by most users.

In addition to the LDAP specific conditions and actions, there are a large number of common conditions and actions available, including Deny, Group, and Stop. See Common Conditions and Actions for more information.

LDAP specific conditions

These are the LDAP specific conditions available and what they test:

IfMember LDAPGroupDN
Tests whether or not the user is a member of the specified LDAP group.
IfRefused
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).
IfTest LDAPAttribute value
True if the user has the specified LDAPAttribute with the specified value.
IfTest -Wild LDAPAttribute value
This variant form of IfTest allows you to specify the value using the * wildcard to match 0 or more characters.

LDAP specific actions

These are the LDAP specific actions available:

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.
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 entry and you receive the error "Operations Error." Add DisableReferralChasing must appear before your URL directive.
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 IfTest 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 IfTest 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)
IfUnauthenticated; 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)
IfUnauthenticated; Stop
/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)
IfUnauthenticated; Stop
IfTest eduPersonAffiliation student; Stop
IfTest eduPersonAffiliation faculty; Stop
IfTest eduPersonAffiliation employee; Stop
IfTest eduPersonAffiliation staff; Stop
IfTest 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)
IfUnauthenticated; Stop
Group General
IfMember 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 IfTest with the groupMembership attribute.

::LDAP
URL ldaps://ldapserv.yourlib.org/OU=users,O=yourlib?uid?sub?(objectClass=person)
IfUnauthenticated; Stop
Group General
IfTest 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"&gt

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