Innovative Interfaces, Inc. (III) authentication

Last updated
Save as PDF

Overview

The III Patron API provides a link for external programs to obtain information on patrons in real-time from the III database. EZproxy provides built-in support to use this interface to verify patron status and authorize remote access.

III system change

To use III authentication, you must first make a change in your III system. The III Patron API must be configured to permit access from the IP address of the EZproxy server. Please consult your III system documentation for additional details.

Create template files

III authentication requires additional files. Create the template versions of these files by entering one of the following commands as appropriate for your operating system:

Command	Operating system
ezproxy -mi	(Windows)
./ezproxy -mi	(Linux)

This command will create the following files in the docs subdirectory. You can and should customize these files as appropriate for your institution.

Filename	Purpose
iexpired.htm	If the patron validates but his/her record is expired, this file is sent.
irefused.htm	If the III system is unreachable, this file is sent.

Barcode validation

The III Patron API will accept but ignore a variety of punctuation within barcodes. The following examples all include the directive:

Not IfUser -RE [0-9]+; Stop

which instructs EZproxy not to attempt to validate anything other than string of all digits.

If your primary field for the III Patron API can include letters, you would change these examples to:

Not IfUser -RE [a-z0-9]+; Stop

If you need additional help creating such a filter, contact support@oclc.org for assistance.

Enable III authentication

To enable the simplest form of III authentication, edit user.txt and add lines such as this to the end of the file:

::III 
Not IfUser -RE [0-9]+; Stop
Host iii.mylib.org
IfRefused; Deny irefused.htm
IfExpired; Deny iexpired.htm
IfUnauthenticated; Stop
/III

replacing iii.mylib.org with the host name of the system running the III Patron API. Changes to user.txt take effect immediately, with no need to restart EZproxy. At this point, you should be able to use library card numbers as usernames with last names as passwords.

Host directive

The Host directive indicates the name of the system where the III Patron API is running. If followed by a simple hostname, EZproxy connects to the specified hostname using the http protocol to port 4500. The hostname may be prefixed with https:// to indicate that an https connection should be used from EZproxy to the III Patron API when making the request. The hostname may be followed by a colon and a port number to indicate that a port other than 4500 should be used when making the request.

Date format

The date format used by the patron API is localized to the format used in your region of the world, but the patron API does not indicate the format, so EZproxy has no way to automatically determine the format of dates it receives. By default, EZproxy assumes that the dates provided by the patron API will be in month-day-year format. If your dates are not in this format, you will need to indicate this to EZproxy by including the "date" keyword, followed by one of "dmy" for day-month-year format or "ymd" for year-month-day format. A sample use for day-month-year format is:

::III 
Not IfUser -RE [0-9]+; Stop 
Date dmy 
Host iii.mylib.org 
IfRefused; Deny irefused.htm 
IfExpired; Deny iexpired.htm 
IfUnauthenticated; Stop 
/III

Please note that the Date directive must appear before the Host directive.

Limit access by patron type

If you need to limit remote database access to patrons who are in specific patron type codes, you can do this by adding "type" lines such as:

::III
Not IfUser -RE [0-9]+; Stop
Host iii.mylib.org
IfRefused; Deny irefused.htm
IfExpired; Deny iexpired.htm
IfUnauthenticated; Stop
IfType 100,105,110; Stop
Deny itype.htm
/III

The Type directive(s) must appear after the Host directive. In this example, a patron must not only validate, but must also have a patron type of 100, 105 or 110 to be authorized for remote access. All other patron types will be denied access and EZproxy will send the itype.htm file (which you create) from the docs subdirectory to explain why access was denied.

Vector notation for III Patron API

The III Patron API was changed for EZproxy 5.2 and later to support multiple use of the same field. For example, if the system has a field named "phone," the first instance might be home, the second might be work, and the third might be cell. Before EZproxy 5.2, user.txt could only access auth:phone and would get the first phone number in the record. Beginning with EZproxy 5.2, if there are multiple field values, they can be accessed by referring to each in the array as auth:phone[0], auth:phone[1], auth:phone[2]. Use the Any family of functions to test the values. If a field is specified without an index, the first (or only) value is returned.

Advanced authentication

Conditions and actions

III authentication is controlled by a series of conditions and actions. Conditions are tests that must be true if the current line is to be considered further. The III specific conditions are IfExpired, IfRefused, IfTest, and IfType. Actions are things that EZproxy should do. The III specific actions are Date, Host, Ignore, and Password.

In addition to the III specific conditions and actions, there are a large number of common conditions and actions available, including Deny, Group, and Stop. See Common conditions and actions for more information.

III specific conditions

These are the III specific conditions available and what they test:

IfExpired: True if the user's account expiration date has passed.
IfRefused: True if the III server refused patron API connection, typically due to the system being down.
IfTest var value[,value...]: Tests an arbitrary patron variable to see if it is among the values specified. var is the short name of the variable such as p53 for the home library; the values may contain the * wildcard to match 0 or more characters.
IfType value[,value...]: Tests the patron type [p47] field against the specified values and returns true if the patron type matches one of these values.

III specific actions

These are the III specific actions available:

Date

Indicates the format of the date when evaluating expiration date. Parameters are MDY (default), DMY and YMD to indicate the sequence in which the Month, Day and Year will appear.

Ignore

When used as an action with the Expired condition, indicates that expired cards should be considered valid; when used as an action with the Refused predicate, indicates that the system should treat the remote user as though their information was valid.

Host

Indicates the name of the system where the III Patron API is running. If followed by a simple hostname, EZproxy connects to the specified hostname using the http protocol to port 4500. The hostname may be prefixed with https:// to indicate that an https connection should be used from EZproxy to the III Patron API when making the request. The hostname may be followed by a colon and a port number to indicate that a port other than 4500 should be used when making the request.

Password

If used, this action must appear before the Host action. This action may appear as "password last" to tell EZproxy to check the login form field "pass" against the last name, "password pin" to check the login form field pass against the user's pin number, "password both" to tell EZproxy to check the login form field "pass" against the last name and to check the login form field "pin" against the user's pin (you must add the field "pin" to login.htm and loginbu.htm if using this option).

PartialNameMatch

Allows matching based on any part of the III patron name field matching any part of the EZproxy password field. For example, if pn is
Smith-Jones Jr, Patricia "Pat" Robin Q, then any of the following would match:

Pat Smith
Smith Patricia
Smith
Jones
Robin Jones
Pattie Smith

Note that Pattie Smith matches, even though Pattie is not present, since Smith is present and does match.

When performing this test, Jr and Sr are ignored. Unless pn is made up of only single characters, single characters are also ignored. As a result, these by themselves would not match:

Jr
Q

To use this form of name match, add the directive PartialNameMatch before your Host line, such as:

::III
PartialNameMatch
Host iii.yourlib.org
/III

Vary EZproxy groups based on III types

This configuration demonstrates how a single condition can accept multiple actions such as the Group and Stop directives, both of which only occur if the condition is true.

::III 
Not IfUser -RE [0-9]+; Stop 
Host iii.mylib.org 
IfRefused; Deny irefused.htm 
IfExpired; Deny iexpired.htm 
IfUnauthenticated; Stop 
IfType 1,2; Group Restricted; Stop 
IfType 3,4,5; Group Default+Restricted; Stop 
Deny itype.htm 
/III

See Groups for more information on EZproxy groups.