This document will define Shadow Users and illustrate how they will be distributed in a consortia implementation of FOLIO. Refer to the ECS Glossary with excerpt below for the definition of terms used in this document.

Shadow users would act as a proxy to allow users in one tenant to perform actions in another tenant. Shadow users would be able to have different permissions than their originating Real User. Staff personnel would not be able to authenticate into their Shadow User, only the Real User. Credentials only live on the Real User. Staff personnel would have to switch contexts to perform actions as their corresponding Shadow User.

Shadow Users are still regular users in the system. There are reasons to create a different type of user to represent a Shadow User e.g. create a new view just for Shadow Users. TBD.

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.

Shadow User Creation

Primary Affiliation Creation

Primary affiliation for a user will be created when a FOLIO user is created in mod-users via domain events.

A user is created in the Home Tenant which will produce a USER_CREATED event. A consumer in the Consortial Tenant will consume the message and create the Primary Affiliation. Cross tenant message consumption is possible because mod-consortia would have access to all topics in a Kafka cluster.

Consortia Authentication

The user's primary affiliation determines the location of their credential, and this information is passed to mod-login. These modules use the information to correctly route requests to the Home Tenant. It is worth noting that mod-login is a core FOLIO module, while mod-consortia is not. If there is a hard dependency from mod-login to mod-consortia, mod-consortia will have to be declared as a core module. To reduce coupling between components, primary affiliations will be passed to mod-login via domain events from mod-consortia. This design choice allows mod-login to function without mod-consortia, which in turn means that mod-consortia will no longer be a core module.

All events will be produced using the transactional outbox pattern.

Non-Primary Affiliation Creation

Assigning an affiliation to a user in the Consortial Tenant will create a Shadow User in the corresponding Member Tenant, whose id is provided in the payload. Only non-primary affiliations will be created by the endpoint below.
HTTP Request:

POST /consortia/df874ff4-c405-11ed-afa1-0242ac120002/user_tenants HTTP/1.1
X-Okapi-Tenant: consortial_tenant
X-Okapi-Token: <JWT>
Content-Type: application/json

{
    "userId": "c7f42744-cf85-47ff-a634-fa24cd35f8a1",
    "tenantId": "target_tenant"
}

HTTP Response:

{
    "id": "67c31a49-2816-43bd-96ef-ff244a4c38e2",
    "userId": "c7f42744-cf85-47ff-a634-fa24cd35f8a1",
    "tenantId": "target_tenant",
    "isPrimary": false
}

mod-consortia will create a user(Shadow User) in the Target Tenant with the same user identifier as the user in the home tenant. The Shadow User will be created with permissions of the user that is trying to create the affiliation.

To reiterate, a Primary Affiliation is assigned when a user record is created in a Member Tenant. A Shadow User record is created in a Target Tenant when a non-primary affiliation is assigned to a Target Tenant.

Shadow User Authorization

Assigning permissions to a user in tenant to which they are affiliated in the FOLIO UI will assign permissions to the Shadow User in the corresponding tenant. Standard calls to assign permissions to a user in FOLIO will be used to authorize the Shadow User.

Shadow User Modification

Primary Affiliation Update [NOT DESIRED]

Functionality to change the primary affiliation of user will be needed during day to day operations of the consortia.

HTTP Request:

PUT /consortia/df874ff4-c405-11ed-afa1-0242ac120002/user_tenants/67c31a49-2816-43bd-96ef-ff244a4c38e2/isprimary HTTP/1.1
X-Okapi-Tenant: consortial_tenant
X-Okapi-Token: <JWT>
Content-Type: text/plain

true

HTTP Response:

true

The distinction between Shadow Users and Real Users is the presence of credentials. Without credentials, authentication is not possible in FOLIO. The shift of the primary affiliation will mean that credentials will need to be deprecated in the current Real User and created for the Shadow User.

The UI forces last name, patron group and email to be set during creation of the user. Without a last name, one can not select a shadow user to add permissions. Also editing a user without these details causes an error during permissions update. This means business logic is bleeding into the UI.

Actions

Find current primary affiliation to get the home tenant.
Remove credentials from Real User in the home tenant.
Require password reset to Shadow User in incoming home tenant.
Update additional information from previous Real User into Shadow User.

It is not desirable to allow primary affiliations to be updated. Especially when password migration is required.

Shadow User Data

Shadow Users will contain the following:

Username
First Name
Last Name
Tenant Id of the Real User stored in a custom property by a special name

There is a chance that an attempt to create a new Shadow User could fail if an existing username is the same as the incoming Shadow User.

Therefore, the Shadow User’s username will random string as a suffix e.g. user_a:<random_string>

TBD how much information is needed in the Shadow User from a business perspective?

Primary Affiliation Deletion

When the Real User is deleted in the home tenant, only primary affiliation will be deleted. This means there will be orphaned Shadow Users and non-primary affiliations without primary for the corresponding user Id. This will be captured by mod-consortia using domain events from mod-users.

A primary affiliation cannot be deleted independently, the Real User has to be deleted instead.

Non-primary Affiliation Deletion

When a non-primary affiliation is deleted, its Shadow User is left in place in the corresponding tenant but deactivated.

Institutional Users

They are users created in the FOLIO that is meant to support edge API interactions. For a consortium, one institutional user should be created in the consortial tenant, and have Shadow Users in every tenant in the consortium. An edge api key would translate to the Real User in the consortial tenant, further context changes to other consortium members can then occur.

Browser not supported