Integrate ILLiad with your local authentication system via EZproxy
The ILLiad patron web pages can be configured as an EZproxy-protected resource, allowing ILLiad patrons to authenticate against any authentication method supported by EZproxy.
Requirements
Caution: This complete document, as well as all of the documentation linked from this page, should be read and
understood before attempting to implement this configuration.
EZproxy - A functional EZproxy installation which makes use of the authentication methods listed in the EZproxy user authentication documentation as well as an EZproxy administrator familiar with EZproxy configuration.
ILLiad - A functional set of ILLiad patron web pages.
Hosted implementations
If you are a hosted ILLiad or EZproxy subscriber, OCLC support can assist you with the configuration settings needed for the hosted service.
Before you begin
These EZproxy ILLiad integration instructions make use of the RemoteAuth ILLiad authentication method and one of the EZproxy authenticate user methods. Please read the documentation related to these methods before you proceed.
You will need the following information before you begin:
| Value | Example | Description |
|---|---|---|
| [ILLiad patron page directory URL] | http://mylib.illiad.oclc.org/illiad/ | The URL of your ILLiad patron web pages |
| [User Header Name] | HTTP_SITENAME_USER | This is the header name you create which will be shared in ILLiad and EZproxy |
| [EZproxy login URL] | http://my.ezproxy_server.edu/login | The URL of the EZproxy server |
Authentication process overview
EZproxy passes the username (set by the authenticating system) to the ILLiad web application (illiad.dll) via an http header.
The header name is a completely arbitrary value that is used in both the ILLiad and EZproxy configuration, referred to in this document as the [User Header Name].
If the header does not contain a username value, patrons are redirected to the authentication method defined in EZproxy, and then returned to the ILLiad web pages.
If the value has been set, the username is checked against the existing users in the ILLiad database.
- If the username matches an existing patron record, the patron is presented with the ILLiad main menu
- If the username does not match an existing patron record, they are taken to the 'NewAuthRegistration.html' page to complete their registration
EZproxy configuration
EZproxy is configured to pass along the username via the AddUserHeader option after authentication.
Authentication is required!
This means:
- There can be no ExcludeIP or AutoLoginIP statements applied before the ILLiad definition, and you will need to force all workstations to authenticate via IncludeIP.
- Referring URL authentication is not valid.
- Simple CGI authentication is not valid.
The most basic definition in the config.txt file will be in this format:
IncludeIP 0.0.0.0-255.255.255.255 AddUserHeader [User Header Name] Title ILLiad URL ILLiad patron page directory URL/illiad.dll AddUserHeader
This definition will most commonly be placed before any other definitions in order to avoid conflicts with other AutoLoginIP and ExcludeIP ranges, as ILLiad does require a username to log in.
If you do not need to place the ILLiad definition elsewhere in the configuration file (due to a Groups statement, or the like), please make sure to include the 'IncludeIP 0.0.0.0-255.255.255.255' statement at the top of the definition.
Note: OCLC Hosted service subscribers: If you also have an OCLC FirstSearch or OCLC WorldCat local definition, you will need to make sure your ILLiad definition is placed before either of those.
ILLiad configuration
Configure ILLiad according to the RemoteAuth instructions.
Logon.htm
In most RemoteAuth configurations, users that access the ILLiad web pages directly are redirected to an authentication service, so the login.html page is removed entirely.
However, EZproxy can only provide proxied access to resources that are passed as arguments to the EZproxy loginURL (e.g. http://my.ezproxy.server/login?url=http://some.proxied.site).
You should create a redirect (or link) on the existing logon.html that sends the user to your EZproxy-protected ILLiad page.
Example: https://support.idm.oclc.org/login?url=http://support.illiad.oclc.org/illiad/illiad.dll
OpenURL
The same Starting Point URL that is used for your login will be used to create your OpenURL Base URL.
Example: https://support.idm.oclc.org/login?url=http://support.illiad.oclc.org/illiad/illiad.dll
This will replace the Base URL in external systems that send bibliographic info into ILLiad (e.g. FirstSearch, SFX).
LocalInfo settings
The same Starting Point URL that is used for your login (https://support.idm.oclc.org/login?url=http://support.illiad.oclc.org/illiad/illiad.dll) will be used to populate the ILLiad system address when you send emails to your patrons (e.g. When you notify them that an article .PDF is ready for viewing).
To configure ILLiad to use this URL, you will need to edit the SystemURL field in the LocalInfo table in the customization manager to match the new StartingPointURL for login.
Example: https://support.idm.oclc.org/login?url=http://support.illiad.oclc.org/illiad/illiad.dll/OpenURL
Example configurations
For this example, the following environmental values are used:
ILLiad logon URL: http://support.illiad.oclc.org/illiad/logon.html
EZproxy login URL: https://support.idm.oclc.org/login
Shared user header name: HTTP_REMOTE_USER
Example ILLiad configuration:
| Customization key | Sample value | Description |
|---|---|---|
| RemoteAuthSupport | Yes | Is RemoteAuth active |
| RemoteAuthUserVariable | HTTP_REMOTE_USER | The name of the header, shared between ILLiad and EZproxy, which contains the username |
| RemoteAuthWebLogoutURL | http://www.oclc.org | The URL to send a user to after logging out of ILLiad |
| RemoteAuthWebPath | C:\inetpub\wwwroot\illiad | The web directory containing ILLiad web files and the DLL that's controlled by remote authentication. In this example, the default web pages are used, but this could be any directory that contained the ILLiad web pages, and were configured as such in IIS |
Example EZproxy configuration:
IncludeIP 0.0.0.0-255.255.255.255
AddUserHeader HTTP_REMOTE_USER
Title ILLiad
URL http://support.illiad.oclc.org/illiad/illiad.dll
AddUserHeader
Note: The traditional 'logon.html' is replaced with 'illiad.dll'