Consortium Authentication

Owned by Olamide Kolawole
Last updated: Aug 08, 2023

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:

  1. Login: Authenticate with a Real User from the consortial tenant context. All logins start from the Consortial Tenant.

  2. 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 InstanceAn Inventory instance that lives in the consortial tenant. Can be shared to other tenant in the consortium.
Shadow InstanceCopy of a Shared Instance in a Member Tenant.

Login

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.