Home

ILLiad/PDS ISAPI Filter Authentication

Overview

The PDSAuth application is an ISAPI Filter developed in Visual C++ for Windows Server and IIS. Its function is to intercept requests to ILLiad (Bobst’s Interlibrary Loan application) in order to verify authentication via PDS and then make an authorization decision based on determining factors discussed below. It was developed as a modification to the CASAuthN filter developed at UC Davis, https://confluence.ucdavis.edu/confluence/display/IETP/CAS+ISAPI+Client.

Application Logic

The application checks on each request to see if there is a valid PDS session and if so redirects back to ILLiad with a local cookie containing the user's N-number encrypted. Then the filter decrypts this username and, if she is a valid ILLiad user, sets an HTTP response header that logs her in. The name for the custom HTTP header is set within the Customization Manager settings (see below).

Authorized?

Once authenticated via PDS, the filter determines if the user is authorized to use ILLiad based on two conditions: borrower status and ILL permission flag.

• If the user has a valid borrower status and has his ILL permission flag set to "Y" he will be passed through the initial authorization.
• Otherwise, if either of these conditions returns false, the user will be redirected to an access denied page defined in the registry. For example: http://library.nyu.edu/errors/ill-library-nyu-edu/access_denied.html.

Expected XML REsponse

NYU has made many customizations to what PDS returns when calling the func=get-attribute&attribute=bor_info request.

The relevant XML fields within this response are <bor-status /> and <ill-permission />.

When the user is valid the API call should return at least the following three fields within <bor-info />:

<bor-info>
  <id>N0000000</id>
  <bor-status>01</bor-status>
  <ill-permission>Y</ill-permission>
</bor-info>

Or when a user is invalid, it expects the following:

<pds>
  <error>Error User does not exist</error>
</pds>

Existing Users

If the user is of a correct borrower status and exists in ILLiad's UsersAll table, she will be logged in. This is the case of an existing user, that is, the user has successfully logged into the application before.

New Users

First time authorized users are a special case.:

• ILLiad will redirect the user to the authenticated user registration page (NewAuthRegistration.html, which we have appropriated as a copyright policy page). This is built-in ILLiad functionality: once the patron is authenticated they are recognized as a new user and are therefore sent to a registration page to fill out additional user information. We require E-mail Address, First Name and Last Name.
• If the user is in the UserValidation table, which is editable through the Customization Manager, her information will be automatically transferred to the UsersAll table and, after agreeing to the copyright policy, she will be logged in. This is thanks to a database-level trigger setup by our DBA to run after each database insert (i.e. entering a new user).
• Otherwise, if the user is not in the UserValidation table, they will be presented with an error message saying to contact ILL staff about getting permission.
• Note: In this last case, if the user should indeed have access to ILL, ILL staff can enter the user into the UserValidation table and the DBA runs a nightly script to sync up the data between the UserValidation and UsersAll tables. Hence, users entered manually into the UserValidation table will experience a lag of at most 24 hours before having access to ILL.
• Technical Note: These error messages are actually manipulations of the required field error messages for E-Mail Address, First Name and Last Name. This seeming hack is in place because the case where that required information cannot be found is the case where the user is valid according to PDS but ILLiad doesn't know about him.

General Note: Users in the UserValidation table are part of a load that our DBA performs each semester. Users created manually in Aleph during the course of the semester will not be in the UserValidation table unless manually entered.