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:

  Default Legal General
Some Database available only to law students   *  
Other Database available to all     *
Another Database available to all     *

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):
  • Legal
  • General

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 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.