ILLiad Web Client Authentication

The ILLiad Web Client supports multiple authentication methods to provide flexibility for different institutional requirements. This article explains how authentication works and how to configure it.

Login Page Behavior

When a user navigates to any page of the Web Client without first logging in, they will be automatically redirected to the login page. What appears on the login page depends on how the Web Client is configured:

ILLiad Authentication Only

If no SSO providers are configured, users will see the standard ILLiad login screen with username and password fields.

SSO Only

The login experience varies based on the number of SSO providers configured:

Single SSO Provider:

• Users will not see an ILLiad login screen
• They will be automatically redirected to their SSO login page
• After successful authentication, users will be redirected to the Web Client home page

Multiple SSO Providers:

• Users will see a dropdown menu listing each configured SSO provider
• After selecting a provider, they will be redirected to that SSO login page
• After successful authentication, users will be redirected to the Web Client home page

Both ILLiad and SSO Authentication

By default, the ILLiad login form is hidden when SSO is configured. However, you can enable both authentication methods simultaneously:

To display both ILLiad login and SSO options, add the following to the Web Client's appsettings.json file:

"AllowILLiadAuthOverride": true

When enabled, users will see both the ILLiad login form and SSO login button(s) or dropdown on the same page.

ILLiad Staff Authentication

Staff members can log in using their ILLiad username and password, just as they do in the desktop client. This authentication method uses the existing ILLiad user database and credentials.

SSO Authentication

If SSO is enabled, users can log in via their institutional Single Sign-On system.

First-Time SSO Login

The first time a user logs in via SSO, they will need to link their SSO account to their ILLiad account:

1. User logs in through their SSO provider
2. After successful SSO authentication, they are prompted to enter their ILLiad username and password
3. This creates a link between their SSO account and their ILLiad account
4. Subsequently, only the SSO login will be needed

This linking process ensures that SSO users are properly associated with their existing ILLiad accounts and permissions.

SSO Configuration

SSO authentication works via the SAML2 protocol. Configuration is done by adding a SAML section to the WebApi's appsettings.json file.

Configuration Format

The configuration format is similar to the SAML module's SAML.config file, but uses JSON instead of XML.

Example Configuration

"SAML": {
  "$schema": "https://www.componentspace.com/schemas/saml-config-schema-v1.0.json",
  "Configurations": [
    {
      "LocalServiceProviderConfiguration": {
        "Name": "https://<server.edu>/illiad",
        "Description": "ILLiad Web Client Service Provider",
        "AssertionConsumerServiceUrl": "https://<server.edu>/illiadapi/auth/sso/authenticate",
        "SingleLogoutServiceUrl": "https://<server.edu>/illiadapi/auth/sso/logout",
        "LocalCertificates": [
          {
            "FileName": "certificates/sp.pfx",
            "Password": "password"
          }
        ]
      },
      "PartnerIdentityProviderConfigurations": [
        {
          "Name": "https://saml.example.com/entityid",
          "Description": "MockSAML",
          "SingleSignOnServiceUrl": "https://mocksaml.com/api/saml/sso",
          "SingleSignOnServiceBinding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
          "PartnerCertificates": [
            {
              "String": "<Base64-encoded certificate string>"
            }
          ]
        }
      ]
    }
  ]
}

Configuration Parameters

LocalServiceProviderConfiguration:

• Name: Your ILLiad instance URL
• Description: Descriptive name for the service provider
• AssertionConsumerServiceUrl: Endpoint for receiving SAML assertions
• SingleLogoutServiceUrl: Endpoint for handling logout requests
• LocalCertificates: Certificate file and password for signing SAML requests

PartnerIdentityProviderConfigurations:

• Name: Entity ID of your SSO provider
• Description: Friendly name for the SSO provider
• SingleSignOnServiceUrl: Your SSO provider's authentication endpoint
• SingleSignOnServiceBinding: SAML binding protocol (typically HTTP-Redirect)
• PartnerCertificates: Base64-encoded certificate string from your SSO provider

tip

Replace <server.edu> with your actual server domain and update all other configuration values to match your institutional SSO provider's requirements.

Multi-Factor Authentication

The ILLiad Web Client supports Multi-Factor Authentication (MFA) for ILLiad username/password authentication to provide an extra layer of security for staff logins.

info

MFA is available for ILLiad username/password authentication. If you're using SSO, MFA is typically handled by your identity provider.

Overview

By default, the ILLiad Web Client will enforce multi-factor authentication for all staff user accounts. On your first login, you will be required to configure MFA for your account using a third-party authentication application such as Microsoft Authenticator. After this configuration is completed, you will need to enter a 6-digit one-time password (OTP) generated by the connected authentication application along with your username and password each time you log in.

Supported Authentication Applications

The following third-party authentication applications have been officially tested and are confirmed to be supported for use with the ILLiad Web Client:

• Microsoft Authenticator - Mobile application
• Google Authenticator - Mobile application
• Twilio Authy - Mobile application
• 1Password - Mobile or desktop application (subscription required)

Other authentication applications offering time-based one-time passwords (TOTPs) not listed above may also work with the ILLiad Web Client. However, as these applications have not been officially tested, support cannot be guaranteed.

Configuring MFA for Your Account

Upon your first login to the ILLiad Web Client, you will be prompted to configure multi-factor authentication for your ILLiad account. Follow these steps to complete this process:

1. Enter the username and password for your staff account into the ILLiad Web Client login screen and click Logon

2. The Multi-Factor Authentication Setup screen will appear. Use your authentication application to either:

   • Scan the QR code displayed on the screen, OR
   • Copy and paste the Manual Entry Key into your authentication application

   This will create an entry for ILLiad in your authentication application.

   tip

   Please refer to your authentication application's documentation for detailed instructions on adding accounts.

3. Enter the one-time password (OTP) generated by your authentication application for ILLiad into the Authentication Code field on the Multi-Factor Authentication Setup screen

4. Click Submit

5. MFA is now configured for your ILLiad account and you will be logged into the ILLiad Web Client

Using MFA After Configuration

After completing the initial MFA setup, you will need to enter the OTP generated by your connected authentication application along with your ILLiad username and password on all subsequent logins to the ILLiad Web Client.

If you lose access to your authentication application or need to change your MFA configuration, your configuration must be reset by an ILLiad administrator to allow you to re-complete the setup process using a new authentication application.

Resetting MFA Configuration for a Staff Account

ILLiad administrators can reset the MFA configuration for a staff account using the Staff Administration page in the ILLiad Web Client. Resetting a user's MFA configuration will allow them to re-complete the MFA setup process in the case that they:

• Lose access to the authentication application connected with their ILLiad account
• Need to switch to a different authentication application
• Get a new mobile device

To reset a staff member's MFA configuration:

1. Log in to the ILLiad Web Client with an account that has StaffManager access
2. Navigate to Staff Administration from the Staff Menu
3. Locate the staff member whose MFA needs to be reset
4. Follow the prompts to reset their MFA configuration

Once reset, the staff member will be prompted to complete the MFA setup process again on their next login.