As of ILLiad 9.1, authentication enhancements have been added that allow ILLiad to map user attribute fields from external authentication systems into the ILLiad User table fields. Staff is able to select which fields can be passed through to update the user record. At each login, ILLiad will validate credentials, verify access, and update any relevant identity data without having to prompt the patron to re-key information for ILLiadExclusive and RemoteAuth. This feature can be leveraged through the use of the Automatic User Creation to automatically create and pre-clear users based on the attribute fields populated with the authentication enhancements feature.
Configuring the RemoteAuthValidation Table
Protected Fields | ILLiadFieldName | Valid & Invalid Action | RemoteFieldName | Troubleshooting the RemoteFieldName Value | Passing a Static Default Value into the User Record | Example Setup
exportDuplicateValues="false"The RemoteAuthValidation table allows data to be mapped from an external source through RemoteAuth or ILLiad Exclusive to an ILLiad user record. This table works similarly to the OpenURLMapping table and is also utilized for web users. If there is any required information for registration that is not seeded in the RemoteAuth headers, then the user will be navigated to finish filling out the new user registration form.
The RemoteAuthValidation table can be modified in the Customization Manager under Web Interface | Authentication.
| Name | Type | Notes |
|---|---|---|
| ID | int | PK |
| NVTGC | nvarchar(20) | Site for this field mapping |
| ILLiadFieldName | nvarchar(40) |
The name of the field as it appears in the Users database table to map to Note: The 'Username' field is case sensitive and must be entered into the RemoteAuthValidation table exactly as written here.
|
| RemoteFieldName | ILLiad 9.1: nvarchar(40) ILLiad 9.2: nvarchar(1024) |
The attribute name used for the field by your RemoteAuth identity provider. ILLiad will receive the value of this attribute from the remote auth system and map it to the ILLiad field designated in the ILLiadFieldName column. If legacy remote authentication handling is enabled via the UseLegacyRemoteAuthHandling key in the ILLiad Customization Manager, the RemoteFieldName column can alternatively contain the name of the HTTP header for the field retrieved from the RemoteAuth identity provider instead of the attribute name. |
| Validation | nvarchar(200) | Regex for validating the remoteauth value |
| ValidAction | nvarchar(50) | Action to take when field passes validation (e.g., substitute) |
| InvalidAction | nvarchar(50) | Action to take when the field does not pass validation (e.g., substitute) |
| ValidDefault | narchar(200) | Substitute value to use if validation passes |
| InvalidDefault | narchar(200) | Substitute value to use if validation fails |
| Overwrite | string | If "Yes", replace ILLiad value with remoteauth value. If "IfBlank" or "No", only set changes if the ILLiad field value is blank. If not, don't save changes to ILLiad.Users. |
| LogIfChanged | bit | If true, write a logline if this field is changed. By default, the checkbox is left NULL in the client. |
Protected Fields
|
|
|
ILLiadFieldName
The ILLiad field used in the ILLiadFieldName column must be formatted with the name for that field as it appears in the Users database table (with the exception of the 'Username' field which must be formatted exactly as written here). The name used for a field in the database may be different from the name used for that field on the web pages or in the ILLiad Client. To see the list of field names as they appear in the Users database table, refer to the ILLiad Database Tables documentation.
Examining the code for each field within the HTML files for user-related forms on the ILLiad web interface (such as NewUserRegistration.html) can help identify the database names that should be used for those fields. However, the names used for several fields in the ILLiad web page HTML code are different from the names used for those fields in the ILLiad database. Please use the table below to help identify the correct database name for each of these fields that should be used in the ILLiadFieldName column of the RemoteAuthValidation table:
| Field Name in Web Page Code | Database Field Name |
| LoanDeliveryGroup | LoanDeliveryMethod |
| WebDeliveryGroup | Web |
| DeliveryGroup | DeliveryMethod |
| StatusGroup | Status |
ValidAction & InvalidAction
| Actions | Values |
|---|---|
| accept | Uses the value of the remoteauth field |
| substitute | Use the default value set in ILLiad |
| reject | Do not accept user (this will not write to the user record and it will not allow the user to login to ILLiad) |
| ignore | Do nothing for this field |
| replace |
[ILLiad v9.2] Modify the incoming remoteauth field value before writing it to the ILLiad database. For more information, expand the detailed information on using this action below. This action can only be used in the "ValidAction" field entry.
|
The ValidDefault and InvalidDefault responses are determined by the actions selected for the ValidAction and InvalidAction.
The 'replace' action added to the RemoteAuthValidation table in ILLiad v9.2 differs from the existing 'substitute' action, which substitutes the entire incoming remote field value with the value defined in the ValidDefault column, in that it will instead allow you to choose how to modify or replace parts of that remote field value before it is written to the ILLiad database. This is done by using a series of regular expressions in the Validation and ValidDefault columns as follows:
- Using regular expressions, define a group or groups of values to be captured from the incoming remote field in the Validation column. Groups are defined by a set of parentheses and will be numbered starting at an index of 1 from left to right.
- Use appropriate numbered group replacement expressions ($1, $2, etc.) in the ValidDefault column to define how those group(s) captured from the remote field value should be used to modify the value before it is written to the ILLiad database.
Listed below are some examples to help you use this new feature:
Example 1 - Removing Text from a Remote Field Value
- Validation = (\w+)@domain\.edu
- ValidDefault = $1
In this case, the text contained in the incoming remote field value that is located before '@domain.edu' will be captured and written as-is to the ILLiad field. For example, if the incoming remote field value is 'username@domain.edu', the value written to the ILLiad field will be 'username'.
Example 2 - Adding Text to a Remote Field Value
- Validation = (\w+)
- ValidDefault = $1@domain.edu
In this case, the entire text contained in the incoming remote field value will be captured and written to the ILLiad field with '@domain.edu' appended to the end. For example, if the incoming remote field value is 'username', the value written to the ILLiad field will be 'username@domain.edu'.
Example 3 - Changing Case of a Remote Field Value
- Validation = (.+)
- ValidDefault = \U0
In this case, the entire text contained in the incoming remote field value will be captured and converted to uppercase before it is written to the ILLiad field. For example, if the incoming remote field value is 'text', the value written to the ILLiad field will be 'TEXT'. Similarly, a lowercase conversion can be done using the '\L' expression.
RemoteFieldName
The RemoteFieldName column should contain the attribute name used for the field by your RemoteAuth identity provider (IdP). ILLiad will receive the value of this attribute from your IdP's remote authentication system and map it to the ILLiad field designated in the ILLiadFieldName column, and as such, you must ensure that each attribute used in this table is an attribute that has been released by your IdP. Note that attribute names will vary by IdP, so it is recommended that you contact your IdP directly to obtain the correct values.
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 as follows:
- Coordinate with your IdP and/or local IT staff to obtain the name of the attributes you wish to use in the RemoteAuthValidation table, ensuring that each attribute has been released by the IdP
- Fill out the RemoteAuthValidation table with this information, mapping the IdP attributes to ILLiad fields according to your preferences
- Once the table has been completed, switch the value of the GetBuildInfoShowDetailed key in the ILLiad Customization Manager to Yes
- Navigate to the GetBuildInfo page in your web browser by entering the following URL: https://yourILLiadServerURL/ILLiad/illiad.dll?getbuildinfo
- The name of each attribute that has been released by your IdP and configured with the proper RemoteFieldName in the RemoteAuthValidation table will appear on this page
- Check the listed attributes against your entries in the RemoteAuthValidation table to ensure that all attributes are passing to ILLiad as expected
- If an attribute is missing, please contact your IdP or local IT staff for further troubleshooting
Obtaining the RemoteFieldName Using Legacy RemoteAuth Handling
Note: This option is not available for use with the integrated SAML module.
If legacy RemoteAuth handling is enabled via the UseLegacyRemoteAuthHandling key in the ILLiad Customization Manager, the RemoteFieldName column can alternatively contain the name of the HTTP header for the field retrieved from the RemoteAuth identity provider instead of the attribute name. You can then check for the attributes currently released by your IdP using the GetBuildInfo endpoint, where they will appear as HTTP headers. You can access this endpoint by switching the GetBuildInfoShowDetailed key in the ILLiad Customization Manager to Yes and then navigating to https://yourILLiadServerURL/ILLiad/illiad.dll?getbuildinfo.
Migrating from a Pre-existing ILLiad 9.0 RemoteAuth Configuration
In ILLiad 9.1, the RemoteAuthUserVariable Customization Key was removed. The value of this key is now seeded to the new RemoteAuthValidations table as part of the update process for each NVTGC that has enabled RemoteAuthSupport. When using ILLiadExclusive, the RemoteFieldName should be the same name as the ILLiad User FieldName in the UserValidation table. For ILLiadFieldNames of StatusGroup, please trim the expression down to Status only. The default will use the following values:
- ILLiad FieldName = Username
- Validation= .+
- ValidAction= accept
- InvalidAction= reject
- Overwrite= no
- LogIfChanged= false/unchecked
Passing a Static Default Field Value into the User Record
If you would like a certain field to contain a static default value for your ILLiad user records, you will have to configure an entry for that field with this default value specified in the RemoteAuthValidation table. This will set the field in the user's database record to that value, which will also pre-populate the value for that field on the NewAuthRegistration and ChangeUserInformation web pages.
For example, if you would like all user records to contain a LoanDeliveryMethod field value of "Hold for Pickup" by default, you would need to create the following entry for the LoanDeliveryMethod field in the RemoteAuthValidation table:
| NVTGC | ILL |
| ILLiadFieldName | LoanDeliveryMethod |
| RemoteFieldName | ILLiadDefault_LoanDeliveryMethod |
| Validation | .+ |
| ValidAction | ignore |
| InvalidAction | substitute |
| ValidDefault | NULL |
| InvalidDefault | Hold for Pickup |
| Overwrite | No |
| LogIfChanged | Yes |
- The NVTGC column should contain the relevant NVTGC value that should be set in the user record
- The ILLiadFieldName column should contain the name of the ILLiad database field for which to set the default value
- The InvalidDefault column should contain the default value you want to pass into that field
- The RemoteFieldName column should be given a value that does not exist in the remote headers so that the field will always fail validation and thus populate with the static value specified in the InvalidDefault column
Example Setup
| ID | NVTGC | ILLiadFieldName | RemoteFieldName | Validation | ValidAction | InvalidAction | ValidDefault | InvalidDefault | Overwrite | LogIfChanged |
| 1 | ILL | NVTGC | ShibIdentityProvider | *urn:mace:incommon:institution.edu* | substitute | reject | yourNVTGC | Yes | No | |
| 2 | ILL | Username | eppn | .+ | accept | reject | No | Yes | ||
| 3 | ILL | Lastname | sn | .+ | accept | reject | Yes | Yes | ||
| 4 | ILL | Firstname | givenName | .+ | accept | reject | Yes | Yes | ||
| 5 | ILL | SSN | barcode | .+ | accept | substitute | 123123123 | Yes | Yes | |
| 6 | ILL | EMailAddress | .+ | accept | reject | Yes | Yes | |||
| 7 | ILL | Department | ucDepartment | .+ | accept | substitute | Unspecified | Yes | Yes | |
| 8 | ILL | Cleared | entitlement | *urn:mace:dir:entitlement:common-lib-terms* | substitute | substitute | Yes | No | Yes | Yes |
| 9 | ILL | Status | affiliation | *staff@institution.edu* | substitute | ignore | Staff | Yes | No | |
| 10 | ILL | Status | affiliation | *graduate@institution.edu* | substitute | ignore | Graduate | Yes | No | |
| 11 | ILL | Status | affiliation | *undergraduate@institution.edu* | substitute | ignore | Undergrad | Yes | No | |
| 12 | ILL | Status | affiliation | ^faculty@institution.edu$ | substitute | ignore | Faculty | Yes | No |
When is RemoteAuthValidation Considered
AuthType of RemoteAuth:
When using RemoteAuth, ILLiad will always try to determine the username by evaluating the "Username" There is no "login" process when using RemoteAuth so updates that are found when evaluating the RemoteAuthValidation table will be applied if the user's LastChangedDate and the WebSessionMinutes added together are less than the current Date/Time.
The ILLiadFieldName entry will utilize the current NVTGC. If your site has a shared server setup and the current NVTGC is ILL, the alternate NVTGC will be determined from the RemoteAuthValidations mappings (ILLiadFieldName of NVTGC). Once the alternative NVTGC is determined, that NVTGC will be loaded to then check for Username.
AuthType of ILLiadExclusive:
RemoteAuthValidation is only used for applying updates to existing users. If sites want to preserve current functionality where data is only imported when the record is created the first time, the site would not add any entries to the RemoteAuthValidation table. The data will be applied when a user successfully logs in. Data is not imported if the user entered an invalid username/password, was disavowed, blocked, or locked out of their account.