ILLiad Product Specific Considerations for Self-hosted Remote Authentication Implementation

danger

A bug introduced in Shibboleth v3.2.2.2 may cause variable values to be duplicated in User records created through RemoteAuth. To resolve this issue, please use the following setting in your Shibboleth RequestMapper configuration:

exportDuplicateValues="false"

RemoteAuth authentication is slightly different than other authentication methods in that there is no default product logon page used for customers to enter a username and password. Instead, customers are redirected to the site's authentication server (IdP for example), which retrieves the username value. If the username has been set, it checks to see if the session is still active. If it's active, they will be taken to the ILLiad web pages. If the username value has not been set, the customer is taken to the authentication server's logon page and prompted for credentials before proceeding to ILLiad.

ILLiad installations have successfully authenticated users via SAML based Single Sign-on (SSO), PubCookie, CoSign, and Shibboleth, using this type of authentication. Shibboleth, which uses SAML, being the most popular.

Currently, ILLiad only checks for the username and does not look for other customer information (i.e. name, status, contact information, etc.).

Note that RemoteAuth authentication is dependent on your existing external authentication system. In order to use RemoteAuth authentication with ILLiad, you must create a means to protect the ILLiad web folder and send an authenticated username, usually with an ISAPI filter or module. If you are using Shibboleth, for example, you would install and configure the Shibboleth Service Provider (SP) software on the ILLiad web server. For the username value, remoteAuth authentication expects a server variable (EPPN or uid for example) that is returned from the authenticating system and passed to ILLiad via the HTTP header. Because the development and support of 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 can help you troubleshoot the ILLiad portion of the authentication, we cannot install, configure, or diagnose issues related to the authenticating system.

It is helpful to include your local SSO administrator, your ILLiad server administrator, ILLiad processing staff, and your Atlas Systems support representative in a project planning kickoff meeting. It is also recommended to keep your local IT Security informed of your authentication goals and progress.

ILLiad Specific Settings

IIS Components (Web Directories | Protected Directory | Unprotected Directory)

Web Directories

• Two web directories, an unprotected and protected, usually located under the Default Web Site in IIS
• Typical ILLiad setup will have ILLiad default authenticated users, so you will need a landing page to give patrons the choice of ILLiad or remoteauth authentication.
• To create the protected directory, replicate the ILLiad default web pages to a new folder, rename to "remoteauth" for example, copying all contents and permissions

Unprotected Directory – default ILLiad web pages

• Required for Staff access from the ILLiad Client
  • Default Document – product logon HTML page

Protected Directory – a copy of ILLiad web pages

• Provides a direct link to ILLiad web interface, routes users to SSO interface
  • Protected by the remote authentication
  • Default Document - ILLiad.dll

Customization Keys

The following is a list of Customization Keys that will need to be updated in the ILLiad Customization Manager to reflect the web directory configuration created for remote authentication.

Key Name	Value
AuthenticationMethod	ILLiad (if RemoteAuthSupport set to Yes, this key will be ignored)
RemoteAuthSupport	Yes
RemoteAuthUserVariable	Unique identifier released by the authentication system
RemoteAuthWebLogoutURL	Site supplied URL to direct the patron to after logout
RemoteAuthWebPath	Local path to the protected directory
SystemURL	URL for the protected directory
WebServiceURL	URL for the web service in the unprotected directory

Additional Information

danger

Shibboleth attribute IDs must be written using all uppercase letters in attribute-map.xml for the associated variable to pass through to the ILLiad DLL.

• Set the GetBuildInfo ILLiad Customization Key to Yes first.
• ILLiad installations typically require careful consideration of existing user authentication methods
  • Note: As of ILLiad v8.6 and above ILLiad will only consider single variables instead of HTTP_*
  • When requiring SAML elements be sent to ILLiad, are the attribute policies updated as needed so they are released to the SP?
  • When building the RemoteAuthUserVariable, utilize the RemoteAuthUserVariable table documentation for more information
• When allowing dual access (both SSO and traditional login), the unique identifier used must be consistent
  • A test server is very helpful during the implementation of SSO. If you need a quote for Atlas to install and support a local test server, please let us know.
  • RARE: If allowing users to login to ILLiad without authentication via SSO, a dual auth portal would need to be installed, configured, and customized. A quote is issued only if Atlas web design services are needed.
  • If a username conversion is needed in order to make existing ILLiad users have the username that matches the RemoteAuthUserVariable, Atlas staff can perform a username conversion. An estimated fee for this service is $1500. Please send your planned username format to your ILLiad Support representative if this conversion service is needed.
  • A test server is very helpful during the implementation of SSO. If you need a quote for Atlas to install and support a local test server, please let us know.
• Go to https://yourservername/illiad/illiad.dll?getbuildinfo to help confirm the name of remoteauth attributes actually being released and username
• Using an Authentication Portal Landing Page

Sample Responsibility Matrix:

Task	Responsible	Notes
Schedule project kickoff meeting	Local staff	Include SSO administrator, your ILLiad server administrator, ILLiad processing staff, IT Security staff (optional), and your Atlas Systems support representative
Create & install Certificates if needed	Local staff
Notify end users of changes and potential downtimes for implementation and testing	Local Staff	A test server can minimize this impact
Install and configure Shibboleth on local ILLiad server	Local staff
Install Dual Auth Portal & Authentication Landing Page (if needed)	Local staff with Atlas Support if needed	Atlas Auth Portal 13.x Release Configuration Using an Authentication Portal Landing Page
Update ILLiad Customization Keys	Local staff with Atlas Support if needed
Customize web pages to indicate new login credentials required (if needed)	Local staff with Atlas Support if needed
Test & Troubleshoot	Local staff with Atlas Support if needed