RemoteAuth: Configuring the Integrated SAML Module

Brittany De Gail

Updated March 11, 2024 20:43

As of v9.2, ILLiad contains integrated support for Remote Authentication via Security Assertion Markup Language (SAML) meaning that additional software will no longer need to be installed on the ILLiad Server to communicate with authentication systems based on SAML, such as Shibboleth and OpenAthens. The Atlas SAML module uses SAML 2.0 and will be downloaded as a new component to C:\ILLiad\SAML when updating to or installing the ILLiad 9.2 Server. This article will provide an overview of how to configure this module, which is also detailed in the readme.txt file found in the module's installation location.

Note: If you have already configured Shibboleth or another SAML-based system to work with ILLiad you should continue using your existing solution upon updating to ILLiad v9.2. The integrated SAML module is intended as a solution for those unable to install their Service Provider module on the ILLiad Server.

Terms Used in this Article

The following terms and abbreviations will be used throughout this article to describe the configuration process:

Security Assertion Markup Language (SAML): A protocol used by many authentication systems, such as Shibboleth and OpenAthens.
Service Provider (SP): A system to which access is governed by an authentication system. In this case, the SP is the ILLiad Server.
Identity Provider (IdP): A system that authenticates users and transmits information about them to a Service Provider. In this case, the IdP is your particular SAML-based authentication system.
Protected Path: A URL path on a server that can only be accessed after authenticating with an IdP (e.g., https://server.edu/ILLiad).

Installation Information

The Atlas SAML module will be added as a new ILLiad server component when updating to or installing the ILLiad 9.2 Server and the files used to configure and install the module on the ILLiad Server will be downloaded to the default path C:\ILLiad\SAML. These files include:

Two SAML configuration files (SAML.config and IdpMapping.config) used to configure the SAML module to work with your IdP.
A PowerShell script (InstallSamlModule.ps1) used to install the SAML module on the ILLiad Server.

Note: Though the files used to install the SAML module will be downloaded as part of the 9.2 server update, the module itself will not be installed until the PowerShell installation script is run. Please see the Configuration Overview section below for more information on this process.

Configuration Overview

To configure the ILLiad SAML module, you and your hosting provider will need to work together to configure settings in the ILLiad Customization Manager and in the configuration files included with the SAML module, and your hosting provider will also configure new or existing SP and IdP certificates on your ILLiad Server. Once this process is complete and the module is configured, you may also need to provide metadata on the ILLiad SAML Service Provider to your IdP before you can begin authenticating users. You can find a brief step-by-step overview of the configuration process, as well as details and guidelines for completing each step in the relevant sections below.

Configuration Steps and Responsibilities

Sites using EZproxy should also refer to the RemoteAuth: Transitioning to the SAML Module from EZproxy article for additional information on testing and transitioning from EZproxy to the SAML module.

The recommended order for completing this process is outlined below, but may be adjusted depending on your institution's preferences. Steps designated to local staff means that staff members at your institution, including any necessary campus or institutional IT personnel, should complete that process. Hosting staff refers to steps that should be completed by your ILLiad server administrator (these steps would be completed by local staff if self-hosted):

Local staff - Work with local IT staff and your IdP to set up the RemoteAuthValidation table in the ILLiad Customization Manager. See RemoteAuthValidation Table Values below for more guidance on this process.
Hosting staff - Use the instructions in the SAML.config file to configure this file with the institution's IdP metadata.

Local staff should provide hosting staff with their detailed IdP metadata to complete this process. Please refer to your IdP's documentation for details on obtaining this information.

OpenAthens users can find instructions for accessing their metadata in the OpenAthens documentation.
Hosting staff - Configure IdP certificates on the ILLiad Server and update the SAML.config file manually with the certificate information. The SAML.config file will contain detailed instructions on completing this process.
Hosting staff - Run the InstallSamlModule.ps1 script to create SP certificates, automatically update the existing SAML.config file, and add the SAML module to IIS. See Running the InstallSamlModule.ps1 Script below for more guidance on this process.

Note: Running InstallSamlModule.ps1 will remove the manual formatting in the SAML.config file provided to ease navigating and editing this file. It is recommended to finish editing the SAML.config file before running the script.
Hosting staff - Complete the provided idpMapping.config configuration file according to the instructions in the file's comments. Briefly enable the SAML module to obtain the SAML metadata and send to the institution for use in the next step. Disable the SAML module until the next step is completed by the institution. The idpMapping.config file will contained detailed instructions for enabling and disabling the SAML module.

Note: Please restart the IIS service after enabling the SAML module.
Local staff - Provide the SAML metadata sent to you by your hosting provider to your IdP, if necessary. See Providing ILLiad SAML Metadata to your IdP below for more information.
Hosting staff - Reenable the SAML module in the idpMapping.config file once local staff has successfully provided the metadata to their IdP and then restart the IIS service.
Local staff - Enable remote authentication by configuring the rest of the RemoteAuth customization keys in the ILLiad Customization Manager (this will completely activate the SAML module if step 7 has been completed). Your hosting provider will provide you with the specific values to enter in each customization key.

SAML Configuration Files

Note: These files must be edited using a text editing application opened with the Run as Administrator option.

Two configuration files, idpMapping.config and SAML.config, will be downloaded along with the SAML module in C:\ILLiad\SAML after updating your ILLiad Server to v9.2 and will be the main tools used to configure the SAML module for enhanced security and to avoid storing sensitive information on the ILLiad database. Local IT staff will need to obtain the detailed IdP metadata for your institution and provide this information to your hosting provider to help them configure these files. A brief overview of the information that will need to be configured in each file is detailed below:

SAML.config: This file contains information about the Service Provider (i.e., your ILLiad Server) and the Identity Provider, including Entity IDs, sign-on and logout URLs, and signing/encryption certificates (see Signing/Encryption Certificates below).
idpMapping.config: This file determines which URLs on the ILLiad Server are protected by the SAML module (i.e., the protected path) and contains comments indicating which values should be used.

Updating the idpMapping.config file should be the final step for your hosting provider in configuring the SAML module, i.e. it should be done after completing the certificate configuration and SAML.config.

ILLiad Customization Manager

As with other remote authentication setups, local staff must configure your ILLiad Server to use RemoteAuth in the ILLiad Customization Manager before the SAML module can be used. This process includes two steps:

Configuring the RemoteAuthValidation table to indicate how ILLiad should map user attribute fields from your external authentication systems into the ILLiad User table fields. For more information on configuring this table, see Authentication Enhancements: RemoteAuthValidation Table.
Enabling Remote Authentication in ILLiad (and thereby activating the SAML module once it is fully configured) by configuring several additional RemoteAuth customization keys. For information on configuring these keys, see RemoteAuth: Customizing Settings.

Please note that the second step should be completed after the SAML module certificates and configuration files are configured as it will enable the module to begin authenticating your ILLiad users. Please also ensure that your RemoteAuthValidation table is properly configured before activating the module.

RemoteAuthValidation Table Values

Listed in the table below are example configuration values for the Username, EMailAddress, Firstname, and Lastname ILLiad fields and their corresponding SAML attributes for an OpenAthens configuration in the RemoteAuthValidation table. We recommend including entries for these four fields at a minimum when configuring this table.

For more information on setting up this table, please refer to the RemoteAuthValidation table documentation.

Example Configuration (OpenAthens)

ID	NVTGC	ILLiadFieldName	RemoteFieldName	Validation	ValidAction	InvalidAction	ValidDefault	InvalidDefault	Overwrite	LogIfChanged
1	ILL	Username	username	.+	accept	reject			No	Yes
2	ILL	EMailAddress	emailAddress	.+	accept	ignore			No	Yes
3	ILL	Firstname	forenames	.+	accept	ignore			No	Yes
4	ILL	Lastname	surname	.+	accept	ignore			No	Yes

Please note that since this example configuration is based on an OpenAthens setup, your RemoteFieldName values for each field may differ from those used in the example above depending on your specific IdP. It is recommended to contact your IdP for information on the SAML attribute names that should be used in the RemoteFieldName column for each field you add to the RemoteAuthValidation table.

Each row configured for a field in the RemoteAuthValidation table must correspond to an attribute released by your IdP. Please refer to your IdP's documentation for information on configuring your released attributes.

OpenAthens users can find detailed information on this process in the OpenAthens documentation. To view a video tutorial of this process in OpenAthens, please click here.

Troubleshooting the RemoteFieldName Value

Once the RemoteAuthValidation table is completed, you can test your setup with the GetBuildInfo ILLiad endpoint to ensure that each attribute has been configured properly. Please see Troubleshooting the RemoteFieldName Value in the RemoteAuthValidation table documentation for more information on this process.

Signing/Encryption Certificates

The SAML module makes use of X509 certificates for signing and encrypting SAML messages and responses. There are two types of certificates that must be configured on the ILLiad Server:

Service Provider certificates that the SAML module will use to sign/encrypt messages. To configure these certificates, your hosting provider will run the InstallSamlModule.ps1 script located in C:\ILLiad\SAML.
Identity Provider certificates that your IdP uses to sign/encrypt messages. Your hosting provider will use the IdP metadata you provide to them to create and configure these certificates on your ILLiad Server.

Running the InstallSamlModule.ps1 Script

Hosting providers should run the InstallSamlModule.ps1 script after the SAML.config file is fully completed with the IdP metadata in order to configure the service provider certificates on the ILLiad Server. This script should be run following the steps below:

Note: Running InstallSamlModule.ps1 will remove the manual formatting in the SAML.config file provided to ease navigating and editing this file. It is recommended to finish editing the SAML.config file with the IdP metadata before running the script.

Open Windows PowerShell using the Run as Administrator option.
Navigate to the C: drive using the following command:
```
cd\
```
Navigate to the SAML module location on the ILLiad Server using the following command:
```
cd illiad\saml
```
Run the installer script using the following command:
```
.\installsamlmodule.ps1
```
The SAML module has been successfully installed if you are returned to the SAML module location in Powershell as shown below:

Providing ILLiad SAML Metadata to your IdP

After the SAML module is fully configured in each of the configuration files detailed above, your IdP will likely need metadata about the ILLiad SAML Service Provider before it can authenticate users. Once the SAML module is configured, this metadata will be available at https://yourILLiadServerURL/ILLiad/metadata. Your hosting provider will download this metadata and provide it to you once the module has been configured in order for you to provide this information to your IdP. Please refer to the information provided by your specific IdP and/or local IT staff to complete this process.

OpenAthens users can find instructions for completing this process in the OpenAthens documentation. To view a video tutorial of this process in OpenAthens, please click here.