Skip to main content
OCLC Support

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.

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'