User Authentication


The purpose of EZproxy is to provide a simple system that allows you to create one set of web pages that can be used by both on-site and off-site users to gain access to licensed databases. Typically, there is no requirement to authenticate on-site users, but there is a requirement to authenticate remote users to verify their affiliation with your institution. EZproxy provides the ability to detect on-site workstations and redirect their database requests to your database vendor, while requiring remote users to undergo one validation per browser session to verify their right to access a restricted resource.

This page starts by addressing the means available to authenticate remote users, indicates where the login pages are located for you to customize, then explains how to identify on-site workstations to exclude them from authentication and proxying.


You probably already have some existing system that can authenticate your users. This might be your automation system, an e-mail system, some form of computer accounts on a system, or a database that can be extracted into a text file.

All user authentication is controlled with the user.txt/ezproxy.usr file. To create your initial testing username and password, you can edit this file with a text editor and add a line like this:

someuser: somepass

replacing someuser with your preferred username and somepass with your preferred password.

If you want to create an administrative user, add a line like this:

someuser: somepass:admin

In this example, admin is literal text that you add to let EZproxy know that this is an administrative user. See EZproxy Administration for more information on administrative users.

The following web pages describe the steps required to enable authentication against existing systems.

There are also two custom ways to perform authentication:

In the simpler external script version, EZproxy handles user interaction during login as with any of the options above, and at the point where a user's credentials need to be checked, EZproxy connects to your script, provides the user credentials, and expects your script to provide back a valid/invalid indication.

In the more complex CGI version, EZproxy reroutes the entire authentication process to your script and your script is responsible for all aspects of user authentication. This method is more difficult to implement, but provides the greatest flexibility.

If you would like to limit the number of times that a single username can be used to access EZproxy, see Limit Concurrent Logins for configuration details.

Using Deny to block specific usernames

In some instances, it may be necessary to block a single username for authenticating, such as generic accounts, guest accounts, or accounts that have been compromised. To block one or more accounts, add lines similar to this as the very first lines of user.txt/ezproxy.usr:


For these lines to be effective, they must appear in user.txt/ezproxy.usr before any lines that would allow the specified usernames to authenticate, since once a username is authenticated, EZproxy stops processing user.txt/ezproxy.usr.

Changing the login pages

Your main EZproxy directory contains a subdirectory named docs. In the docs subdirectory, you will find two web pages: login.htm and loginbu.htm. The login.htm file is sent to a user when EZproxy needs to perform user authentication. If the user provides invalid information, he/she receives the loginbu.htm file for another chance to login.

If you want to include graphics on these login pages, you will need to use complete URLs that point to a web server holding these files since EZproxy will not serve graphics files out of the docs subdirectory. The graphics can come from a separate web server running on the same system as EZproxy, or a different system.

Identifying on-site workstations

Under normal circumstances, there is no need nor desire to authenticate users who are working on-site from your workstations. If you do not already have the IP addresses of your local workstations, you should check with your information technology department for this information to be able to proceed.

You identify the IP addresses used within your library to EZproxy by editing config.txt/ezproxy.cfg and adding one or more lines similar to:


In most instances, these "ExcludeIP" lines should appear near the top of your config.txt/ezproxy.cfgfile, before the first "Title" line of the first database.

Any address specified in this range will automatically bypass EZproxy. If you want to be able to test EZproxy from a particular local address, you can include the specific address back into proxying with an "IncludeIP" entry. For example, if you want to have address require authentication, you might use these two lines:


This excludes most of your local addresses from proxying, but includes your specific address back into requiring authentication for testing.

Note: Whenever you edit config.txt/ezproxy.cfg, you must stop then restart your EZproxy server to make the changes take effect.

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »