NetLibrary

Minimum version required

The options described in this document require EZproxy 4.0h GA (2007-07-11) or later.

EZproxy 4.0h introduces support for NetLibrary Single Sign-on User Authentication. In this configuration, EZproxy does not proxy access to NetLibrary, but instead interacts with NetLibrary using their Single Sign-on User Authentication to allow the traditional NetLibrary login process to be replaced by the EZproxy login process.

Overview

In the new configuration described below, EZproxy is not used to proxy access to NetLibrary. Instead of proxying access, EZproxy uses encryption technology to authenticate your users for access to NetLibrary resources.

When a user authenticates for NetLibrary access, EZproxy creates a "persistent identifier" for the user. The persistent identifier is an arbitrary series of letters and digits that is uniquely assigned to the user. Each time the same user accesses NetLibrary, the same persistent identifier will be used for the user. However, the value of the persistent identifier gives no personally identifiable information about the user, so the persistent identifier does not provide any information for the identity of the user. In an instance of abuse, NetLibrary can provide your library with the persistent identifier and you can use the EZproxy administration page to cross-reference back to the original user if necessary.

Backing up ezproxy.tkn

The persistent identifiers are stored in the file ezproxy.tkn. If this file is lost, all correlation between your users and their persistent identifiers is lost, disrupting all accounts. To avoid disruption of service caused by server crash, you are encouraged to insure that this file is backed up on a regular basis.

User authentication method requirements

To maintain persistent identifiers, EZproxy requires unique user login information, and most EZproxy user authentication methods provide such information. AutoLoginIP and referring URL are incompatible since they do not provide unique user information. Sites that use CGI authentication should insure that they are providing "loguser" information to associate distinct user information.

If you have any questions regarding user authentication requirements, contact support@oclc.org .

Configuration

The traditional EZproxy NetLibrary configuration looked similar to this:

Title NetLibrary
URL http://www.netlibrary.com/
Domain netlibrary.com


with a number of variations on the Domain lines involved.

The NetLibrary Single Sign-on User Authentication configuration looks like this:

Title NetLibrary
URL http://www.netlibrary.com/
NetLibrary libraryid

Note that there are no Domain or DJ directives involved in this configuration.

NetLibrary will provide you with the libraryid to use. In addition, you will be provided with a file named libraryid.txt. In the directory where EZproxy is installed, you will need to create a directory named netlibrary (all lower case) and place the libraryid.txt file into this directory.

This definition is compatible with starting point URLs that may already be in your catalog such as:

http://ezproxy.yourlib.org:2048/login?url=http://www.netlibrary.com/urlapi.asp?action=summary&v=1&bookid=75848


If a remote user clicks such a link, the user is required to log in, and then the user is sent through the NetLibrary Single Sign-on User Authentication. In this instance, the remote user is automatically logged into an account at NetLibrary that is linked to the user's EZproxy account.

If a user accesses such a link from an IP address that has been identified as local through an ExcludeIP directive, the user is taken directly to the link without being required to log in. If the user selects an option in NetLibrary that requires an account, NetLibrary redirects the user back to EZproxy for the user to log in, and then EZproxy returns the user to NetLibrary after the login completes.

If you decide you would like all local users to be required to authenticate before going to NetLibrary, you can move your NetLibrary database definition so it appears in config.txt/ezproxy.cfg before any ExcludeIP (E) directives.

Example: local users not required to log in until they access an account-based feature such as checkout

This example demonstrates how to configure EZproxy to allow local users to access NetLibrary content without being required to log into EZproxy first. The placement of EZproxy after the ExcludeIP line is the crucial detail in this configuration, since it directs EZproxy to send local users straight to NetLibrary without challenging them to authenticate. If the user encounters a feature where the user is required to authenticate, NetLibrary will reroute the user to EZproxy at which time EZproxy will require the user to authenticate and then return the user to NetLibrary.

Name ezproxy.yourlib.org

ExcludeIP 192.168.0.0-192.168.255.255

Title NetLibrary
URL http://www.netlibrary.com/
NetLibrary libraryid

Title Some Database
URL http://www.somedb.com/> Domain somedb.com


Example: local users required to log in before can access NetLibrary

This example demonstrates how to configure EZproxy to require everyone to authenticate before accessing NetLibrary. The placement of EZproxy before the ExcludeIP line is the crucial detail in this configuration, since the absence of any ExcludeIP before NetLibrary directs EZproxy to require all users to authenticate.

Name ezproxy.yourlib.org

Title NetLibrary
URL http://www.netlibrary.com/
NetLibrary libraryid

ExcludeIP 192.168.0.0-192.168.255.255

Title Some Database
URL http://www.somedb.com/> Domain somedb.com


Example: consortium with more than one NetLibrary account

This configuration demonstrates how to use EZproxy groups to associate different sets of users with different NetLibrary accounts. This configuration requires additional work during user authentication to associate users with the correct groups to allow access. Refer to Groups for more information on configuring groups.

Title NetLibrary
URL http://www.netlibrary.com/
NetLibrary -Group=library1 libraryid1
NetLibrary -Group=library2 libraryid2
NetLibrary -Group=library3 libraryid3


In this configuration, you will have need three separate files from NetLibrary, one for each libraryid.