ILLiad Product Specific Considerations for Self-hosted Remote Authentication Implementation

Print Friendly and PDF Follow

Product ILLiad
Version 8.7 or higher
KB Permissions Public
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:
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.

By default, ILLiad only checks for the username and does not look for other customer information (i.e. name, status, contact information, etc.) unless the RemoteAuthValidation table has been configured to accept additional RemoteAuth attributes.

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 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

  • Typically three+ web directories, usually located under the Default Web Site in IIS
    • Shibboleth Protected Web Directory
    • Non-Shibboleth Protected Web Directory
    • Dual Auth Portal Landing page to allow selection between Shib or Nonshib authentication (not needed if not allowing nonshib users)
      • Landing Page is built from AtlasAuthPortal that can be found on the ILLiad Downloads page. A quote is issued only if Atlas web design services are needed.
    • If a shared server, each site may have separate pages.
      • If the shared site wants to implement remote auth, they get their own web directory in both the shib protected and nonshib protected web directory.
      • If the shared site doesn’t use shib, they will only have a web directory in the nonshib web directory
    • Replicate the directory from the default installation by copying all contents and permission to new shibboleth and non-shibboleth protected web directories 

Protected Directory

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

Unprotected Directory

  • Required for nonshib users (which is common for ILLiad) and Staff Proxy access from the ILLiad Client
    • Default Document –product logon HTML page
    • Lending Pages – Illiadlending.dll
    • WebCirc
    • Reports

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
WebAuthType   ILLiad
RemoteAuthSupport  Yes

Unique identifier released by the authentication system

The RemoteAuthUserVariable key is only applicable to ILLiad 9.0 and any previous versions. ILLiad 9.1 has replaced this key and added a Username entry to RemoteAuthValidation table. See Authentication Enhancements for more information.
RemoteAuthWebLogoutURL Site supplied URL to direct the patron to after logout 
RemoteAuthWebPath   Local path to the protected directory
StaffProxyWebURL  URL for the unprotected directory
SystemURL    URL for the unprotected directory 

Set RemoteAuthValidation Username field the same as RemoteAuthUserVariable customization key without the initial HTTP_prefix.

Additional Information

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 GetBuildInfoShowDetailed Customization Key to Yes then Go to https://yourservername/illiad/illiad.dll?getbuildinfo to help confirm the name of remoteauth attributes actually being released and username.
    • Note: As of ILLiad v9.1.2, by default ILLiad will now only consider server variables instead of HTTP headers when retrieving the values of RemoteFieldName from the RemoteAuthValidation table. These server variables will only appear using the GetBuildInfo endpoint after they have been successfully released by the IdP to ILLiad and configured properly in the RemoteAuthValidation table. Please see Troubleshooting the RemoteFieldName Value in the RemoteAuthValidation table documentation for more information on troubleshooting this process.
  • Shibboleth Staff and ILLiad staff will need to agree and confirm the unique identifier for username
    • If RemoteAuth usernames are different than existing ILLiad usernames, Atlas can correct by performing a username conversion at an estimated fee of $1500. Please request a quote if needed.  Alternatively, users can re-register and staff can manually merge old accounts to the new ones at a time.
  • 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. 

Sample Responsibility Matrix:




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

Local Staff with Atlas Support if needed

Using an Authentication Portal Landing Page

Atlas Auth Portal 1.3.x Release Configuration

Update ILLiad Customization Keys

Local staff with Atlas Support if needed


Customize web pages, including Dual Auth Portal if used, to indicate new login credentials required (if needed)

Local staff with Atlas Support if needed


Test & Troubleshoot

Local staff with Atlas Support if needed




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

Contact Support