Configuring ILLiad to Use OpenAthens

Print Friendly and PDF Follow

As of v9.2, ILLiad provides an integrated SAML module that can be used as an alternative to the configuration method described in this article in that case that you are unable to install Shibboleth on your ILLiad Server.

ILLiad handles OpenAthens authentication as it does for all other Remote Authentication systems.  The remote authentication system will need to provide a mechanism to protect the ILLiad web folder and send an authenticated username. This is often handled with an ISAPI filter or an IIS module which supplies ILLiad with the username that is sent by the authenticating system and passed to ILLiad via the HTTP header or server variable.

Since the development and support of those ISAPI filters or other configurations for authenticating systems are outside of ILLiad, you will need to be familiar with how to create and support those yourself to use this type of authentication.

While Atlas Systems and OCLC can help you troubleshoot the ILLiad portion of the authentication, we can't diagnose issues related to the authenticating system.
The following document contains an example setup. You will need to work with your IT department for further details.
For more information on the basics of Remote Authentication for ILLiad, see RemoteAuth: Authentication Process.

ILLiad and OpenAthens via Shibboleth

There are several different ways to configure OpenAthens via Shibboleth and depending on your network configuration, additional setup procedures that are not listed below may be required. One example of how ILLiad can be configured to authenticate via OpenAthens is as a Shibboleth Endpoint.

To authenticate via OpenAthens through a Shibboleth Endpoint, see the instructions below:

  1. Review the Shibboleth documentation:
  2. Install the Shibboleth software on the ILLiad server. The Shibboleth software includes an ISAPI filter or IIS module by default.
  3. Contact your metadata provider and have them set your local metadata XML file as the source reference point for Shibboleth.
    • Many institutions choose to use InCommon Metadata Federation for easy sharing of metadata with Service Providers.
    • The metadata URL for shibboleth is typical: and is case sensitive for  /Shibboleth.sso/Metadata. This metadata URL is used to configure a custom SAML resource in OpenAthens.
    • OpenAthens metadata provider by URL should work when it is made available by OpenAthens and is accessible by the SP. Some SPs/ILLiad Servers are in a more restricted environment.
  4. Configure attributes for the user identifier.
    • User identifier:
      • This identifier must match the ILLiad username. Typically, the identifier is your local authentication username, but it could potentially be your email address.
    • Attributes:
      • Attributes in Shibboleth are named with URNs and they need to be mapped to server variables or HTTP headers. The Shibboleth attribute-map.xml file defines these mappings.
        • You can use ?getbuildinfo to confirm the name of the attribute actually being released (e.g., ) See RemoteAuthFieldName and HTTP Headers for directions on setting the GetBuildInfoShowDetailed Customization Key in order to view the headers.
        • Username attribute must be released from OpenAthens to the service provider (Shibboleth).
  5. Configure the shibboleth2.xml configuration file.
    • The configuration will vary depending on your local setup and any customizations you may have, version of shibboleth, InCommon membership, etc.
    • Here are some of the fields that may need to be configured:


<Site id="1" name=""/>


<Host name=" " applicationId="https:// ">
<Path name="RemoteAuth" authType="shibboleth"




certificate="" />



 <SSO entityID="">

<MetadataProvider type="XML" file="openathens-metadata.xml"/>


ILLiad Specifics

Once you have the OpenAthens web directory configuration created for remote authentication, you'll need to set up the connection through ILLiad. This requires the following customization keys to be set in the ILLiad Customization Manager.

Customization Key Value
WebAuthType       RemoteAuth
RemoteAuthSupport    Yes
RemoteAuthUserVariable Unique identifier released by the authentication system or the REMOTE_USER server variable
RemoteAuthWebLogoutURL Site supplied URL for clearing cookies after patron ends web session
RemoteAuthWebPath   Local path to the protected directory
StaffProxyWebURL  URL for the unprotected directory
SystemURL   URL for the unprotected directory 

The following web pages should not be protected by Remote Authentication:

  • Lending (Lending web pages)
  • WebCirc
  • WebReports
  • WebPlatform

A duplicate set of ILLiad pages might be necessary if ILL staff intends to be able to log into the web interface as a patron using the "Logon to the web as Patron" option in the ILLiad client. 

Please note that Atlas Systems does not provide technical support for Shibboleth installation, configuration, or operation.  

To initiate a project to integrate your ILLiad server with OpenAthens remote authentication, please contact your OpenAthens and ILLiad support representatives to get the conversation started.


If this article didn’t resolve your issue, please contact Atlas Support for assistance:

Contact Support