Configuring ILLiad to Use OpenAthens

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.

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:
   • Lots of helpful information about Shibboleth can be found here: https://wiki.shibboleth.net/confluence/display/SP3/Home
2. Install the Shibboleth software on the ILLiad server. The Shibboleth software includes an ISAPI filter or IIS module by default.
   • Note: It is recommended to use IIS Server Variables which Shibboleth-SP3 supports by default. Additional configuration is required if upgrading from SP2 to SP3. Refer to the Shibboleth documentation for IIS https://wiki.shibboleth.net/confluence/display/SP3/IIS
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:  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 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 https://illiadservername.edu/illiad.dll?getbuildinfo (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:

<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 set up the connection through ILLiad. This requires the following customization keys to be set in the ILLiad Customization Manager.

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.