Configuring ILLiad to Use OpenAthens

Follow

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 filters to supply ILLiad with a server variable that is set by the authenticating system and passed to ILLiad via the HTTP header. 

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.
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 and ISAPI filter documentation:
  2. Install the Shibboleth software on the ILLiad server. The Shibboleth software includes an ISAPI filter by deafult.
  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 for easy sharing of metadata with Service Providers.
    • The metadata url for shibboleth is typically:  https://service.example.org/Shibboleth.sso/Metadata 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 as long as 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 identifer is your local authentication username but it could potentilly be your email address. 
    • Attributes:
      • Attributes in Shibboleth are named with URNs and they need to be mapped to environment variables or HTTP headers. The Shibboleth attribute-map.xml file defines these mappings. 
  5. Configure the shibboleth2.xml configuration file.
    • 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:

<ISAPI>

<Site id="1" name="illiadservername.edu"/>

<RequestMapper>

<RequestMap>
<Host name=" illiadservername.edu " applicationId="https://
illiadservername.edu ">
<Path name="RemoteAuth" authType="shibboleth"
requireSession="true"/>

<MetaDataProvider>

type="XML"
uri=" illiadservername.edu/sso/saml/metadata"
backingFilePath="abc-metadata-Illiad- illiadservername.edu.xml"
reloadInterval="72000">
</MetadataProvider>

<CredentialResolver>

type="File"
key="illiadservername.edu-key.pem"
certificate=" illiadservername.edu-cert.pem" />
        -->

<ApplicationOverride>

id="https://illiadservername.edu"
entityID="https:// illiadservername.edu"
REMOTE_USER="uid">

 <SSO entityID="https://idp.illiadsite.edu/openathens">
SAML2
</SSO>

<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 setup 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
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 follow 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 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.

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback