The Group directive allows you to create groups of resources, define users of these groups, and assign users access to those resource groups. For example, you can create student, faculty, and alumni groups, and assign access to different resources for each of these groups—students can access a certain set of resources, faculty a different set, and alumni, still a different set. Additionally, you can allow students and faculty to access certain resources while restricting alumni access.
In its default configuration, EZproxy allows all users defined in user.txt to access all databases defined in config.txt. In some instances, it may be necessary to restrict users' access to certain databases. Using the groups configuration allows EZproxy administrators to create groups of resources and define which types of users can access those resources.
Setting up Groups in EZproxy requires configuration changes to the config.txt file to create resource groups. It also requires changes to the user.txt file to add users to the groups named in the config.txt file.
Before getting started with a group configuration, it is important that you understand how EZproxy processes resources in the config.txt file. For more information, review the following documentation:
After you understand how the config.txt file works, it is important to understand some general group restrictions. There may be ways to workaround these restrictions, but the configuration will be more complex.
Because EZproxy reads the origin in a resource's URL to determine how to proxy that resource, the origin also determines whether access to a particular resource can be restricted with groups. Consider the following two examples.
The fictional database provider, Science Database at www.sciencedb.com, has two journals at the following URLs:
You would like to limit access to the Astronomy Journal to only astronomy grad students and the Chemistry Journal to only chemistry grad students. However, EZproxy cannot securely enforce this distinction because EZproxy reads only the origin (http://www.sciencedb.com), and ignores the paths (/astronomy or /chemistry). EZproxy reads these two URLs as the same.
Based on the URL construction of this database provider and its resources, you will not be able to prevent access via groups to the Astronomy and Chemistry journals using only the Group directive and database stanzas. Both URLs begin with the same origin, http://www.sciencedb.com, and this means groups can either access all or none of the Science Database resources.
If instead the URLs for these two resources are constructed as follows:
You would be able to create an Astronomy group with permission to access the Astronomy Journal and a Chemistry group with permission to access the Chemistry Journal by creating separate stanzas for each resource and assigning group access accordingly. The origins of these resource URLs, http://astronomy.sciencedb.com and http://chemistry.sciencedb.com are different and can be configured in two separate stanzas.
For more information about how EZproxy reads and processes URLs, please see Understanding URLs and Database Stanzas and Starting Point URLs and config.txt.
If EZproxy is configured with one IP address, the default, all groups are registered to access content with that IP address. You can configure EZproxy servers with multiple IP addresses, but this is a complex workflow.
Note: The Hosted EZproxy environment does not support servers with more than 1 IP address.
Most content providers cannot differentiate between EZproxy groups. So, if you need to collect statistics about group usage, you will need to add group-specific parameters to your logging directives. For more details, please see Audit and LogFormat.
In example 2 above, the two groups—Astronomy students and Chemistry students—must be defined in the EZproxy user.txt file so that EZproxy can apply the appropriate permissions and restrictions to individual resources. This means that whatever authentication method you select, you must have sufficient information from the authentication method to determine what group the authenticated user belongs to.
Before enabling group access, you should issue one of the following two commands depending on the system you are using to run EZproxy:
Linux: ./ezproxy -mg Windows: ezproxy -mg
This command creates the file logup.htm in the /docs subdirectory where all of your website html files are saved. If a user tries to access a database, but is not authorized to do so, the /logup webpage will be displayed. In its default form, this page appears as a login page with a brief message at the top of the screen explaining that the user does not have the proper group membership to access the resource.
Once the file has been created, editing the logup screen to include a detailed message instructing the user to try different credentials can be useful if users have multiple logins (e.g. multiple library cards with differing access). Depending on your Group setup however, you may want to remove the login form from this file and state that the user does not have access to the database.
The following sample configuration provides an example of a group configuration in both config.txt and user.txt when the authentication method is text file. The syntax in the config.txt file will vary depending on the authentication method you are using for your site, but it will be similar to this example.
If you are using Shibboleth authentication, your groups will be configured in your shibuser.txt file. For additional details about how to configure groups with your authentication method, see Authenticate Users (user.txt).
No matter what authentication method you use, OCLC suggests that you place the least restrictive groups first and then add groups and resources that apply to fewer individuals.
Replace the group names with your group names, and replace the database stanzas with stanzas for your resources. The commented-out lines provide details about what each group setting means.
Group General # All resources in this group are available to everyone because every group defined # in config.txt has access to the General group, and this group of resources is # first in the config.txt
Title Research Database URL http://www.researchdb.com DJ researchdb.com
Title Study Database URL http://www.studydb.com DJ studydb.com
Group GradStudent+Faculty # All resources in this group can be accessed by individuals from the GradStudent and Faculty groups
Title Academic Database URL http://www.academicdb.com DJ academicdb.com
Group GradStudent # All resources in this group are only available to grad students.
Title Student Database URL http://www.studentdb.com DJ studentdb.com
Group Faculty # All resources in this group are only available to faculty. Title Professor Database URL http://www.professordb.com DJ professordb.com
Group Alumni #All resources in this group are only available to alumni. Title Alumni Database URL http://www.alumni.com DJ alumnidb.com
Once you have named groups in config.txt, define the members of each group in your user.txt file.
The sample text below can be entered in your user.txt file to configure groups using text file authentication. The text that has been commented out has been entered to describe the purpose of the directive that follows.
# Allow the following admin user to access all resources and groups ::group=General+GradStudent+Faculty+Alumni rdoe:secret:admin
# Add the undergraduate users in the general.txt file to the group named General. They # will be in the General group but no other groups, so these users will be blocked from # databases following any group besides General in config.txt. ::group=General ::file=general.txt
# Add the graduate student users in the gradstudent.txt file to both the General and # GradStudent groups, so these users have access to all the General and GradStudent resources ::group=General+GradStudent ::file=gradstudent.txt
# Add the faculty users in the faculty.txt file to both the General and Faculty # groups, so these users have access to all the General and Faculty resources. ::group=General+Faculty ::file=faculty.txt
# Add the alumni users in the alumni.txt file only to the Alumni group, so these users can # only access Alumni resources ::group=Alumni ::file=alumni.txt
In the example configuration, rdoe has been added as an administrative user to help diagnose this configuration. If you have not done so, add your admin credentials to all groups as shown in the example tab. Then proceed to test your group configuration. To test your group configurations:
The use of groups is one of the most advanced EZproxy concepts. 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. LDAP, Shibboleth, etc.), and how you will distinguish between various groups of users.