Groups
Overview
In its standard configuration, EZproxy allows all users defined in user.txt/ezproxy.usr to to have access to all databases
defined in config.txt/ezproxy.cfg. In some instances, it may be necessary to restrict access to certain databases to
only certain users. The following document details how to configure EZproxy to implement such restrictions. It assumes
you have a basic understanding of how to configure the config.txt/ezproxy.cfg and user.txt/ezproxy.usr files.
Database vendors versus individual databases from vendors
Before proceeding, it is important to understand that in this discussion, a "database" represents one or more sections of the config.txt/ezproxy.cfg file starting with a Title line, which means
these configuration options really work at the level of a database vendor, not a specific database.
In particular,
EZproxy can vary access between databases provided by two different vendors (e.g. Gale Business ASAP versus
EBSCO Business Source Plus), but normally cannot vary access between two databases provided by the same database vendor (e.g.
Gale Business ASAP versus Gale Expanded Academic ASAP).
Groups
When EZproxy starts processing user.txt/ezproxy.usr and config.txt/ezproxy.cfg
, it starts with the assumption that the current group
is a special group named Default. In the absence of any group directives, all users and all databases are in the
Default group, so everyone has access to everything.
Both users and database definitions can be associated with one or more groups. For a user to gain access to
a database, the user must be in one of the groups associated with
the database.
A Command Before You Start
Before enabling group access, you should issue one of the commands:
| ./ezproxy -mg | | (Linux/Solaris) |
| ezproxy -mg | | (Windows) |
This command creates the file logup.htm in the docs subdirectory. If a user
tries to access a database, but is not authorized to do so, this file will
be sent. In its default form, this page appears as a login page. This
is useful if users may have multiple logins (e.g. multiple library cards with
differing access).
Depending on your needs, you
may want to remove the login form part and change this file to simply state that the user does not have
access to the database.
Sample Configuration
To begin, consider these sample configuration files:
config.txt/ezproxy.cfg
Group Legal
# Databases from here until the next Group statement are in the Legal group
Title Some Database available only to law students
URL http://www.somedb.com
Domain somedb.com
Group General
# Databases from here until the next Group statement are in the General group
Title Other Database available to all
URL http://www.otherdb.com
Domain otherdb.com
Title Another Database available to all
URL http://www.anotherdb.com
Domain anotherdb.com
user.txt/ezproxy.usr
# Make the current group General
::group=General
# Users from the general.txt file will be in the General group
# but not in Legal, so these users will be blocked from Some Database
# but have access to Other Database and Another Database
::file=general.txt
# Now make the current group the combination of General and Legal
# so these users have access to all resources
::group=General+Legal
# Users from special.txt and the rdoe user will be the General and Legal groups
::file=special.txt
rdoe:secret:admin
Most simple group configurations will look like this, with databases
divided into specific groups, and users placed
into combinations of groups to provide them with
appropriate database access.
Testing
In this configuration, rdoe has also been added as an
administrative user to help diagnose the configuration.
If you login as rdoe, you could then go to:
http://ezproxy.yourlib.org:2048/groups
For this configuration, this page would look like this:
This page shows what databases are available to members of what groups.
Note that the Default group exists in all EZproxy configurations,
but since the sample configuration never assigned any databases into the Default group, no database appears in the Default group.
To test user access, you will use these URLs:
http://ezproxy.yourlib.org:2048/login
http://ezproxy.yourlib.org:2048/mygroups
http://ezproxy.yourlib.org:2048/logout
You will use the "login" URL to login to different usernames and passwords from different files. Once
you login, use the "mygroups" URL to see a page like this:
You are a member of the following group(s):
This shows the groups that the user is authorized to access.
The "logout" URL can be used to end your EZproxy session. Once you do this, you can start over with another
with the "login" URL. Using this process, you can verify that users are ending up in the groups as expected.
Assigning Groups With Other Authentication Methods
If you authenticate users using a method like FTP, then your user.txt/ezproxy.usr file might look like this:
::ftp=ftp.yourlib.org
If you would like to authenticate your users by FTP, but would like to place a set of users into a different
group, you would need to change user.txt/ezproxy.usr to look like this:
::group=General+Legal
::ftp=ftp.yourlib.org,file=special.txt
::group=General
::ftp=ftp.yourlib.org
If rdoe and and lsmith were the users who should have restricted access, then special.txt would look like this:
::ignorepassword
rdoe
lsmith
In this configuration, the use of ",file=special.txt" as part of the first FTP access indicates that EZproxy should
first check to see if the user is valid in special.txt before trying to use FTP to authenticate the user. In the
file special.txt, "::ignorepassword" indicates that EZproxy should ignore the password while processing the rest of special.txt,
and instead check just the username. As a result, if the username provided is rdoe or lsmith, EZproxy will try the FTP server for these users,
but won't try it for any other username. If the FTP server authenticated rdoe or lsmith, then the user will login
with Restricted access. If the user does not appear in special.txt, then the first FTP check is skipped. The Restricted
group is then removed from access, and all other users are checked against the FTP server.
This use of ",file=" to act as a filter is valid with all built-in authentication methods, although it is not
compatible with external CGI authentication.
Specific authentication methods
Certain EZproxy authentication methods have their own custom ways of assigning subsets of users into groups.
See the documentation on the specific authentication method for more details.
Confused?
The use of groups is one of the most advanced concepts when using EZproxy. If you know how you want to vary access
among your users, but this information does not provide enough detail for you to proceed, please
send e-mail to support@oclc.org and describe
the databases involved, how you plan to authenticate your users (e.g. text files, FTP, etc.), and how you
will distinguish between various groups of users.
Librarians' Toolbox:
