EDU Authentication and SSO

This article covers how EDU authenticates to the ILLiad Web API — username/password, SSO, token handling and refresh, site resolution, and the endpoints it calls. For configuration and how EDU works, see the EDU Administrator Guide.

When a staff member signs in, EDU authenticates to the ILLiad Web API and receives a bearer token (a JWT) that identifies them for the rest of the session. EDU keeps this token in memory only — it is never written to disk, so closing EDU ends the session.

Username / password

The staff member enters their username and password in the Login window (and a site, on a shared server). EDU sends those to the Web API and gets back an access token to use for the session, a refresh token to renew it, and the time at which the access token expires.

Single sign-on (SSO)

SSO is fully wired. EDU holds no SSO configuration of its own — providers are whatever the ILLiad Web API exposes:

1. Discover providers — EDU requests the configured identity providers. An empty list reports "No SSO providers configured on the server."
2. Select a provider — a single provider is used automatically; multiple providers show a selection window.
3. Browser handoff — EDU opens the SSO login page in your default web browser and waits locally for the sign-in to finish (it listens on a temporary local port for the browser to hand the result back).
4. Callback — when sign-in completes, EDU receives the result (it waits up to 5 minutes), reads the token, and picks up the username and the site to work in.

SSO sessions carry no refresh token today

The SSO callback path stores the token without a refresh token. Automatic 401 refresh (below) applies to the username/password path.

Token handling and automatic refresh

Every call EDU makes to the Web API carries the bearer token (as an Authorization: Bearer <token> header). If the API rejects a call with a 401 (the token has expired or been refused), EDU automatically uses the refresh token to get a new one and retries the call once before reporting a problem. It also checks the token's expiry on its own — with a 5-minute buffer — so it can renew ahead of time. Signing out, or simply closing EDU, clears the token from memory.

Site resolution (which site EDU works in)

EDU always works within one ILLiad site (NVTGC), and it figures out which one like this:

• On a shared (multi-site) server: the site the staff member picks at login is written into their token, and EDU uses that as the current site — so everything it does is scoped to the right site.
• On a single-site server: there's no site in the token, so EDU uses the login selection, then the staff account's own site (ignoring the all wildcard), and finally a default of ILL.

Whichever site EDU settles on is sent with every request it makes. The list of sites in the login picker comes from the Web API; if there's more than one, EDU treats the server as shared and shows the picker.

Web API endpoints used (authentication)

Method	Endpoint	Purpose
POST	auth	Username/password login
POST	auth/refresh	Refresh access token (once, on a 401)
GET	auth/logoff	Logout
GET	auth/sites	Available sites for the shared-server site picker
GET	auth/sso/idps	SSO provider discovery
GET	auth/sso/login	SSO browser-redirect handoff

Auth error handling

Login failures map to user-facing messages: 401 → "Invalid username or password"; 404 → "Authentication endpoint not found - check API URL"; 500 → "Server error - please try again later"; a connection error → "Network error - check your internet connection and API URL"; a timeout → "Connection timeout - server took too long to respond."