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 middleware.internet2.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.
- BindPassword -Obscure obscuredpassword
- Extended form of BindPassword which allows the password to be specified in an non-plaintext format. To create an obscured password, run EZproxy interactively with a command similar to:
which might display the result:ezproxy obscure verysecret
which is then used like this:MnZyU22XEY92rCPXqOrZUmco7ALGBindPassword -Obscure MnZyU22XEY92rCPXqOrZUmco7ALG - 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?filterThe 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.
- UseSearchFilterWhenReadingAttributes
- [RARE] Introduced in EZproxy 5.2 (2009-08-31), this directive allows the search filters that are used in login to also be used when reading attributes when all the attributes are not released by the ACL. For an example of this directive, see "Use search filter when reading attributes" below.
Search using anonymous access using uid
::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">
immediately following the <head> tag to insure that these characters are encoded properly for authentication against LDAP.
Use search filter when reading attributes
The UseSearchFilterWhenReadingAttributes directive, introduced in EZproxy 5.2, supports some highly secured configurations of LDAP. It allows the search filters that are used in login to also be used when reading attributes when all the attributes are not released by the ACL.
::LDAP
BindUser CN=ezproxy,CN=users,DC=yourlib,DC=org
BindPassword verysecret
IfUnauthenticated; Stop
UseSearchFilterWhenReadingAttributes
Set session:uid = auth:uid
/LDAP