This document will illustrate a design for consortial authentication for FOLIO. Glossary of terms are included in a section below. There are two scenarios that needs to be covered:

Login: Authenticate with a Real User from the consortial tenant context. All logins start from the Consortial Tenant.
Simple Request: Any request to a Member Tenant or Consortial Tenant with an authenticated user.

This design assumes that a Real User has been created in a Member Tenant to authenticate and Shadow Users exist in Member Tenants to perform regular request processing in the FOLIO tenant where the Shadow User resides. Shadow Users will share the same identifier as Real Users.

Glossary

Click here to expand...

ECS Glossary

Term	Description
Primary Affiliation	AKA home tenant. Identifer of the tenant of a Real User
Active Affiliation	Current tenant with which FOLIO actions are performed. Only possible if a Shadow User exists in the tenant.
Shadow User	a user created in a destination tenant to allow the principal in an originating tenant to act by proxy in the destination tenant.
Real User	a user created in a tenant. Acts as a primary link to shadow users in other tenants.
Home Tenant	Tenant where the actual user record(Real User) lives
Target Tenant	Tenant context where FOLIO actions are performed
Consortial Tenant	Tenant where mod-consortia is enabled
Central Tenant	AKA Consortial Tenant
Member Tenant	Tenant belonging to a member of a consortium.
Shared Instance	An Inventory instance that lives in the consortial tenant. Can be shared to other tenant in the consortium.
Shadow Instance	Copy of a Shared Instance in a Member Tenant.

An new property, tenantId, is added to the payload to /authn/login which will further help with distinguishing usernames. It is possible that the same username exists in multiple Member Libraries. This property is optional in the payload schema.

A separate flow of events will populate username, tenantId → Home Tenant relationships in mod-login. mod-login will listen to events produced by mod-consortia and create local versions of primary affiliations. This is described in more detail here Shadow Users

Simple Request

Edge API Access

FOLIO edge modules require API clients to provide a Edge API Key for access. This key will map to a user in a FOLIO tenant. In a consortium, the API key will still map to a single user in a single tenant but there will be extra facilities to choose an alternate tenant id for a request. The mapped user in FOLIO will need to have affiliations to the alternate tenants mapped. The tenant id can be received by query parameter or header like other parameters common to edge modules. Modifications will be made to edge-common library.

Browser not supported