ToDo

• Jim Wilson to document what tests may be impacted by this project and report to Accedia
• Jim Wilson to update this requirements document based on discussions in the 2022-11-22 status meeting.

Team

OAGi

• Primary contact: Jim Wilson, Jim.Wilson@OAGi.org, +1 816-516-8847

• Secondary contact: Michael Figura, MFigura@OAGi.org, +1 404-395-8267

NIST

• Score project manager: Serm Kulvatunyou, Serm@NIST.gov

• Score lead dev: Oh, Hakju (IntlCtr), Hakju.Oh@NIST.gov

Accedia

• Account manager and PM: Aleksandar Todorov (Deactivated), aleksandar.todorov@accedia.com

• Primary dev: Stefani Paunova (Deactivated), stefani.paunova@accedia.com

• Tech consultant: Georgi Yolovski (Deactivated), georgi.yolovski@accedia.com

Resources (access todo)

Terminology notes

• It is debatable whether multi-tenant is appropriate to describe this feature, but the name has stuck, so we’re using it.

• role is a critical feature of authorization in this requirements document. In this requirements document, we will use role-related terms as follows:

  • Score role: One of the built-in Score roles (Admin + Developer, Admin + End User, Developer, and End User)

  • Auth0 role: A role defined in Auth0 (this is not relevant for Phase 1 design)

  • tenant: An Auth0 role defined for the purposes of enabling the requirements expressed in the document.

  • role: The meaning could be any of the above depending on the context in which it is used. Jim Wilson recommends avoiding use of role in favor of one of the three terms above.

• access BIEs refers to creating, editing, viewing, and expressing BIEs (anything with BIEs)

• BC: an abbreviation for Business Context

• Dev/Admin: a user in the Admin+Developer Score role

• user's tenancy: refers to association of a user to tenants, or more specifically, the association of a user to a valid value specified for the Tenant context scheme

• Tenant context scheme: The context scheme specified in Score with the name Tenant

Background

OAGi needs:

1. to enable multiple sets of users to use one Score instance

2. to be able to limit access to BIEs created by one set of users to members of that set, and other select sets as appropriate

Key points informing the design

1. Keep the implementation simple until such time that simple won’t work.

2. The following BIE-development roles/purposes must be supported

   1. OAGi develops BIEs for the public (e.g., SME Express Pack)

   2. OAGi develops BIEs for members only (none yet)

   3. Companies develop BIEs for their company only

   4. Companies develop BIEs for their industry (e.g., MilliporeSigma for the Biopharma industry)

   5. Industry associations or consortiums develop BIEs for their industry (e.g., AgGateway)

3. Except for 2.c., there is little/no risk for a company’s confidential information to be publicly disclosed.

4. In the case of 2.c. for company whose BIE design or documentation is highly sensitive, OAGi will advise them to use an on-prem instance.

5. Each BIE is associated with one or more business contexts.

6. Each user must be in one of the Score roles.

Phase 1 Design

Multi-tenant Score design

1. Phase 1 of Multi-tenant Score will use the current built-in capability for authentication, and for authorization of Score roles. Accedia will develop further authorization functionality based on a user’s tenancy.

2. Score 2.5 and later will be released with:

   1. A context category named Tenant

   2. A context scheme named Tenant (based on the context category Tenant)

3. No user (not even Dev/Admin) may delete or rename the Tenant context scheme (Accedia will need to implement restrictions.)

4. No user (not even Dev/Admin) may delete or rename the Tenant context category. (Accedia will need to implement restrictions.)

5. Only Dev/Admin may manage values in the Tenant category scheme. (Accedia will need to implement restrictions.)

6. Dev/Admin may manage all business contexts, whether or not the user is associated with any tenant. (This is supported today, but Accedia will need to ensure that other restrictions it implements do not inadvertently restrict this.)

7. Only Dev/Admin may add or delete a Tenant context scheme value to a BC that has BIEs associated with it. (Accedia will need to implement restrictions.)

   1. Why? This should prevent two undesirable situations:

      1. a user assigning a Tenant context scheme value to a BC that does not have one assigned, thereby restricting access to that BIE

      2. a user assigning another Tenant context scheme value to a BC that already has a Tenant context scheme value associated with it, thus potentially unintentionally enabling access to many users

8. When creating a BC, users may only use Tenant context scheme values matching the user's tenancy. (Accedia will need to implement restrictions.)

9. Only a user with the appropriate tenancy may manage a business context containing a Tenant context scheme value. (Accedia will need to implement restrictions.)

10. Users may be associated with zero or more tenants where the possible tenants are those specified as valid values for the Tenant context scheme. (Accedia will need to develop new functionality, including database changes/additions that store data about the associations.)

11. A user may only access BIEs:

    1. associated with at least one business contexts that has as least one Tenant context scheme value matching the user’s tenancy.

    2. associated with business contexts that do not include a Tenant context scheme value.

Another way to think about #11 is that if any context associated with a BIE has a Tenant context scheme value, then access to that BIE is determined by the user’s tenancy (except for Dev/Admin). Otherwise anyone can access the BIE.

Logical process for determining whether a BIE is accessible

• Is the user Dev/Admin?

  • Yes → The BIE is accessible

  • No → Is the BIE associated with a business context containing a Tenant context scheme value?

    • No → The BIE is accessible

    • Yes → Is the BIE associated with a business context containing a Tenant context scheme value associated with the user’s tenancy?

      • Yes → The BIE is accessible

      • No → The BIE is not accessible

Concrete example

Score roles

• Admin + Developer

• Admin + End User

• Developer

• End User

Tenants

• AgGateway

• ACME Brick

• HR Open Standards

Business contexts

• Human Resources, which includes a Tenant context scheme value = HR Open Standards

• Agriculture, which includes a Tenant context scheme value = AgGateway

• Construction, which includes a Tenant context scheme value = ACME Brick

• Entertainment, which does not include any Tenant context scheme value

Users

• Bob

• Mary

• Amy

• Roy

• Matt

• Tess

• Ross

BIEs - Business Contexts

Users - Roles

Business Contexts - Roles

BIE Visibility to Users

This table would be computed based on the values in the tables above.

• Mary can access all BIEs because she is a Dev/Admin. Dev/Admins can access everything.

• Matt can only access:

  • BIEs in a business context that include the Tenant context scheme value ACME Brick, which is the Construction business context.

  • BIEs in a business context that does not include any Tenant context scheme value

• Tess can only access BIEs in a business context associated with the AgGateway tenant.

  • BIEs in a business context that include the Tenant context scheme value AgGateway, which is the Agriculture business context.

  • BIEs in a business context that does not include any Tenant context scheme value

• Ross can only access BIEs

  • BIEs in a business context that include the Tenant context scheme value ACME Brick, which is the Construction business context.

  • BIEs in a business context that include the Tenant context scheme value AgGateway, which is the Agriculture business context.

  • BIEs in a business context that does not include any Tenant context scheme value.

Implementation

Update database structure

We plan to start the multi-tenancy implementation with the following DB changes:

• Replace the organization column in the app_user table with a foreign key to a new table, called organization, that will be used for the tenants

• Create a mapping table between organizations and business contexts (many-to-many) that will keep track of each tenant’s access to BIEs in a certain business context

Phase 2 Design (in progress)

Identity Provider

OAGi has an Auth0 account and has been using it for #E authentication and authorization. Following are a couple of screen captures that illustrate how it can be configured to support Score multi-tenant.