EZproxy has a built-in tool for developing your LDAP configuration. To access this tool, start with EZproxy Administration for information on how to login as an administrator. Once you are at the EZproxy administration page, select Test LDAP then use the following procedure to determine the needed configuration.
- Configuring LDAP, and the instructions below, are full of exceptions because it's a protocol, not a specific application that always functions in the same way for all sites, such as CAS.
- Multiple configurations can be used to search different LDAP servers or different LDAP containers.
- The configuration generated by this test should be entered in the user.txt file, and a restart is not needed.
Before Getting Started: In the majority of LDAP installations, anonymous search is disabled. For production use, you will need to create an account and assign it to EZproxy to use for searching the directory. The account does not require special privileges, but only the ability to search the directory and read attributes you want to test.
Confirm that EZproxy can connect to the LDAP server.
In the Host field, enter the name of your LDAP server. If you have a forest with multiple domains, enter the name of one of the domain controllers that holds the user information against which you want to authenticate.
- Do not place ldap:// or ldaps:// in front of the host.
- If your server is on a non-standard port, add a colon (:) and the port number at the end of the name.
- If a default secure port is being used, select the SSL box.
Note: If you use LDAP with Active Directory, select Disable referral chasing.
Click find search base.
If EZproxy is unable to connect, check the following:
- Is the information entered above correct?
- Is there a firewall issue between the EZproxy server and the LDAP server? Try connecting to the LDAP server on that port
- If the LDAP server is in a different network, it is setup to be seen from the EZproxy network? Try an nslookup for the LDAP server from the EZproxy server or network.
- Does the LDAP server need to whitelist the EZproxy server to allow connections?
- Identify and enter the Search Base.
When the search base has been found, at the bottom of the page, you should see at least one search domain. You may see choices that start DC=ForestDnsZones or DC=DomainDnsZones, either of which should normally be ignored. Click on the most appropriate search domain, which should move it up into the Search Base box.
- Enter the remaining LDAP information.
The minimum required fields for most cases have been marked with an asterisk below.
- Bind Username and Password*: Being able to query the LDAP server varies by system.
- Some systems are anonymous bind, which means no bind username or password is needed.
- Some systems allow any valid LDAP user to perform a search. In this case, the person setting up LDAP would be able to use their own credentials as bind user. Note that they may need to use a different format for the bind user (see below) than the standard ID used to log in.
- Some systems require a bind user - an LDAP account with privileges that allow the user to perform a query. The username may be in one of several forms:
- A simple ID may be allowed. An example would be ezproxybind
- Some require the ID with the server address. An example would be firstname.lastname@example.org
- Many require the id in full distinguished name (DN) syntax. An example would be cn=ezproxybind,ou=employees,dn=college,dn=edu.
Note: If you are troubleshooting your LDAP configuration and already have an LDAP stanza in user.txt, but you do not know your password and you are using EZproxy V6.1 or later, you can retrieve the obscured password from your user.txt and enter it here. Look for the following line in user.txt:
and copy and paste the obscured password following -Obscure into the Bind Password field on the Test LDAP page.
BindPassword -Obscure MeLWS4Pw9Tz7D2Y954HOloi8er
- LDAP Version*: Select 2 or 3. Leave 3 selected by default if you are uncertain. If you get an error or no results switch to 2.
- Use SSL*: This box should have been selected in step 1 if your LDAP server uses a secure port (https).
- SSLCipherSuite: This option was introduced in EZproxy v6.1.13. Generally, this option is left blank; however, enter TLSv1 if you are attempting to connect to a Windows 2003 Server, and your initial connection test fails.
- Host[:port]*: This field should be populated with the Host entered in step 1.
- Search Base*: This field was populated in step 2.
- Include subcontainers in search: This option is selected by default. Leave this selected for your first test.
- Disable referral chasing: This option should have been selected in step 1 if your LDAP is Active Directory.
- Search Filter*: Leave as (objectClass=person).
- Search Attribute*: The most common choice for Active Directory is sAMAccountName.
- Test User*: Enter just the user part of your account (e.g., someuser).
- Test Password: If your first test is successfull, you can enter your password for the test user and searching again to determine if the password is correct. See the final bullet point in the Results section below for more information.
- If you get an Invalid Credentials error, then the Bind User or Bind Password is likely incorrect. Verify these values and try to search again.
- If you get an Operations Error, check to see if Disable Referral Chasing is selected. If it is not selected, select it and search again.
- If you receive no errors and a stanza is generated, but the search returns no results, do not use this stanza. You may have the Test User or Search Attribute wrong. Try clearing the Test User box and search again. If the search still returns no results, select the Filter. If these check out, try clicking find search base to see if you have any other search bases to try.
- If your search is successful, you should see extended detail from your account. If this is the case, try entering your password in the Test Password box and try to search again. The DN section of the search results should indicate that the password is correct. At this point, if you scroll to the bottom of the page, you will find a sample of the entry you should copy and paste in user.txt.
Note: For production use, you should create an Active Directory account for EZproxy to use for searching and substitute this account in your configuration.
Once you have the basic entry working, refer to LDAP Authentication for information on additional tests based on group membership and attributes assigned to accounts.
This page last revised: March 24, 2016.