Central Authentication Service (CAS)

Minimum version required

Most of the directives described in this document require EZproxy 3.6d GA (2006-03-17) or later.

The original CAS support appeared in EZproxy 3.4c GA (2005-08-02) and is documented toward the end of this page.

Configuration

To enable Central Authentication Service (CAS), edit user.txt/ezproxy.usr and add lines similar to:

::CAS
LoginURL http://www.yourlib.org/cas/login
ServiceValidateURL http://www.yourlib.org/cas/serviceValidate
/CAS


By default, the use of CAS disables EZproxy's normal login methods, including the presentation of the login menu.

This form also supports the general directives Admin, Allow, Authenticated, Banner, Debug, Deny, Group, Invalid, NoGroups, Refused, Stop, Unknown, User, and UsrVar, plus a specialized version of Test to check tag values using an XPath to specify the tag to check. For example:

::CAS
Debug
LoginURL http://www.yourlib.org/cas/login
ServiceValidateURL http://www.yourlib.org/cas/serviceValidate
Group NULL
Test -RE cas:group (Undergrad|Grad); Group +Student
Test //*/cas:group Employees; Group +Employee
Test /cas:authenticationSuccess/cas:groups/cas:group Staff; Group +Staff
NoGroups; Deny unaffiliated.html
/CAS


For this example to work, config.txt/ezproxy.cfg would need to default the Student, Employee, and Staff groups as well.

The Debug directive tells EZproxy to record additional diagnostic messages to messages.txt/ezproxy.msg. This includes recording the entire XML response from the Service Validation URL, which can help in sorting out which attributes are available to use for making authentication decisions.

In all three tests, the tag cas:group is being tested. The first and second tests use an identical search to locate tags, as EZproxy assumes a search from the root across all nodes if no path infomation is included. The third test uses an absolute path to the tag.

Filtering CAS results through other authentication methods

To filter the CAS results to limit which users are authorized to access EZproxy, you can add a file directive, such as:

::CAS,File=filter.usr
LoginURL http://www.yourlib.org/cas/login
ServiceValidateURL http://www.yourlib.org/cas/serviceValidate
/CAS


The file filter.usr can contain any user.txt/ezproxy.usr directives.

A sample filter.usr to lock out select usernames might look like this:

::IgnorePassword
user1::Deny
user2::Deny
*


The ::IgnorePassword tells EZproxy that it does not need to perform password checking, which is important in CAS filtering since EZproxy does not handle the user's password at any point when using CAS. The next two lines indicate that any username matching user1 or user2 should not be allowed access. The final line with just * indicates that all other usernames should be allowed access.

A sample filter.usr to allow only specific usernames might look like:

::IgnorePassword
user1
user2


The ::IgnorePassword tells EZproxy that it does not need to perform password checking, which is important in CAS filtering since EZproxy does not handle the user's password at any point when using CAS. The next two lines indicate that any username matching user1 or user2 should be allowed access. Any other username would not be allowed.

The filter file can also contain a reference to an external script, such as:

::External=http://www.yourlib.org/cascheck.cgi,post=user=^u


After a user is authenticated by CAS, EZproxy would connect to the script and this script would make the authorization decision regarding whether or not the user should be permitted access to EZproxy.

CAS support was first added in EZproxy 3.4a GA (2005-08-02) or later. That original syntax is still supported and is entered in user.txt/ezproxy.usr similar to this:

::CASLogin=http://www.yourlib.org/cas/login,CASServiceValidate=http://www.yourlib.org/cas/serviceValidate


changing the URLs to point to your institution's CAS login and service validate URLs.