Configuring the ILLiad Web Client

This guide covers the configuration steps required to set up the ILLiad Staff Web Client after installation. The Web Client consists of two components that must be properly configured:

• ILLiad Web Client (illiadstaff) - The browser-based staff interface
• ILLiad Web API (illiadapi) - The backend API that the Web Client communicates with

Prerequisites

Before configuring the Web Client, ensure:

• ILLiad Server 10.0 or later is installed
• IIS is installed and configured per the Server Configuration and Permissions guide
• .NET 8.0 Runtime (including ASP.NET Core Runtime) is installed on the server
• SSL certificate is installed (HTTPS is required)
• WebSocket Protocol feature is enabled in IIS

Installation Locations

After running the ILLiad Server installation, the Web Client components are installed to:

Component	Default Location
Web Client	C:\ILLiad\WebClient
Web API	C:\ILLiad\WebApi
Indexing Service	C:\ILLiad\IndexingService
Search Indexes	C:\ILLiad\Search\Indexes

Configuration Steps

Step 1: Configure the Web Client appsettings.json

The Web Client's configuration file is located at C:\ILLiad\WebClient\appsettings.json.

Critical Configuration - ApiBaseUrl

During installation, the ApiBaseUrl setting is automatically configured based on IIS detection. However, this auto-detection may fail or produce incorrect results, especially for:

• OCLC-hosted sites
• Sites with non-standard IIS configurations
• Sites without a hostname binding configured in IIS

If the Web Client cannot connect to the API after installation, this setting is the most likely cause.

Open C:\ILLiad\WebClient\appsettings.json and verify or update the ApiBaseUrl:

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiBaseUrl": "https://your-server.edu/illiadapi/",
  "ApplicationPath": "/illiadstaff/",
  "FileSizeLimit": 2097152,
  "CacheExpirationSeconds": 60,
  "SearchSettings": {
    "AutoSearchEnabled": true,
    "DebounceDelayMs": 1000,
    "MinimumQueryLength": 2
  }
}

ApiBaseUrl Requirements:

• Must use https:// (SSL is required)
• Must include your actual server hostname
• Must end with /illiadapi/ (lowercase, with trailing slash)
• For OCLC-hosted sites, use your site-specific URL (e.g., https://yoursite.illiad.oclc.org/illiadapi/)

Common Issue

If the installer could not detect your IIS hostname, ApiBaseUrl may be set to https://localhost/ILLiadApi/ or contain a placeholder. This must be updated to your actual server URL.

Step 2: Configure the Web API appsettings.json

The Web API configuration file is located at C:\ILLiad\WebApi\appsettings.json.

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Warning",
      "Microsoft": "Warning"
    }
  },
  "AllowedHosts": "*",
  "RequireMultiFactorAuthentication": false,
  "FileSizeLimit": 2097152,
  "CacheExpirationSeconds": 60,
  "Search": {
    "IndexBasePath": "C:\\ILLiad\\Search\\Indexes",
    "TaxonomyBasePath": "C:\\ILLiad\\Search\\Taxonomy"
  },
  "Indexing": {
    "IncrementalUpdateIntervalSeconds": 60,
    "BatchSize": 1000,
    "BatchProtectionThreshold": 100
  }
}

Key Settings:

Setting	Description
RequireMultiFactorAuthentication	Set to true to enforce MFA for all staff logins
Search.IndexBasePath	Path to Lucene search indexes (must match Indexing Service config)
Search.TaxonomyBasePath	Path to taxonomy data for search
FileSizeLimit	Maximum upload file size in bytes (default: 2MB)

Step 3: Verify IIS Configuration

Both the Web Client and Web API should be configured as applications under your IIS website.

Verify Application Pools

Open IIS Manager and confirm the following application pools exist:

Application Pool	.NET CLR Version	Managed Pipeline Mode
ILLiad Web API	No Managed Code	Integrated
ILLiad Web Client	No Managed Code	Integrated

Note

The application pool names include spaces: "ILLiad Web API" and "ILLiad Web Client"

For each application pool, verify these settings in Advanced Settings:

Setting	Required Value
Enable 32-Bit Applications	True
Load User Profile	True

The installer automatically sets Load User Profile = True, but this should be verified if you experience authentication or cryptography-related errors.

Verify Web Applications

Under your Default Web Site (or ILLiad website), confirm these applications exist:

Application	Physical Path	Application Pool
illiadstaff	C:\ILLiad\WebClient	ILLiad Web Client
illiadapi	C:\ILLiad\WebApi	ILLiad Web API

warning

The application names illiadstaff and illiadapi must be lowercase in IIS.

Verify WebSocket Protocol

The Web Client requires WebSocket support for real-time features. The installer attempts to enable this automatically, but verify it is installed:

1. Open Server Manager
2. Go to Manage → Add Roles and Features
3. Navigate to Web Server (IIS) → Web Server → Application Development
4. Ensure WebSocket Protocol is checked

Step 4: Set Folder Permissions

Ensure the IIS_IUSRS group has appropriate permissions:

icacls C:\ILLiad\WebClient /grant IIS_IUSRS:(OI)(CI)RX
icacls C:\ILLiad\WebApi /grant IIS_IUSRS:(OI)(CI)RX
icacls C:\ILLiad\Search /grant IIS_IUSRS:(OI)(CI)RX

Step 5: Restart IIS

After making configuration changes, restart IIS:

iisreset

Verification

Test the Web API

Navigate to the Web API base URL in a browser:

https://your-server.edu/illiadapi/

You should see an API response or documentation page indicating the API is running.

Test the Web Client

Navigate to the Web Client URL:

https://your-server.edu/illiadstaff

You should see the ILLiad Web Client login page. Attempt to log in with valid ILLiad staff credentials.

Troubleshooting

Web Client Cannot Connect to API

Symptoms: Login fails with a connection error, or the page loads but shows API errors.

Solutions:

1. Check ApiBaseUrl - Open C:\ILLiad\WebClient\appsettings.json and verify ApiBaseUrl contains your correct server URL with https:// and a trailing slash
2. Test API directly - Navigate to the API URL in a browser to confirm it's accessible
3. Check CORS - Ensure both applications are on the same domain
4. Check browser console - Open developer tools (F12) and look for network errors

500 Internal Server Error

Solutions:

1. Check the Windows Event Log (Application log) for detailed error messages
2. Enable detailed errors in appsettings.json by setting "DetailedErrors": true
3. Verify database connection - the Web API connects to ILLiad using the same connection as other ILLiad components
4. Ensure .NET 8.0 Runtime and ASP.NET Core Runtime are installed
5. Verify application pool settings match the requirements above

403 Forbidden Error

Solutions:

1. Verify folder permissions for IIS_IUSRS on WebClient and WebApi directories
2. Check that application pools have Load User Profile set to True
3. Ensure SSL certificate is valid and properly bound to the site
4. Verify Windows Authentication is not blocking access (Web Client uses its own authentication)

Application Pool Crashes or Stops

Solutions:

1. Verify Enable 32-Bit Applications is set to True
2. Verify Load User Profile is set to True
3. Check Windows Event Log for crash details
4. Ensure .NET 8.0 Runtime is properly installed
5. Test running the application manually:

   cd C:\ILLiad\WebApi
   dotnet AtlasSystems.ILLiad.WebApi.dll

Search Not Working

Solutions:

1. Verify the ILLiad Indexing Service is running (check Windows Services)
2. Confirm Search.IndexBasePath in WebApi appsettings.json matches the Indexing Service configuration
3. Ensure the search index directories exist and have proper permissions
4. Check Indexing Service logs at C:\ILLiad\IndexingService\Logs

MFA/Authentication Issues

Solutions:

1. If MFA is causing issues, temporarily disable by setting "RequireMultiFactorAuthentication": false in WebApi appsettings.json
2. For SSO configuration issues, see Web Client Authentication
3. Verify the user account exists and is active in ILLiad

Related Documentation

• Server Configuration and Permissions
• Hardware and Software Requirements for Version 10.0
• Web Client Authentication
• Web Client Overview & Home Page