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.

...

• 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. Auth0 provides the capability to create users, roles, and user-role associations. 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 initialism for Business Context

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

• user's tenancy: refers to association of a user to tenants

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 should will advise them to use an on-prem instance.

5. Each BIE must be “in” a business context.

Design

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.

...

1. is associated with one or more business contexts.

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

Phase 1 Design

Multi-tenant Score design

...

This design only affects BIE access. This design would not apply to CC access.

...

Score will use Auth0 for authentication and authorization.

1. Out of the box, Auth0 supports

   1. Managing users

   2. Managing roles

   3. Managing user-role relationships

...

Only administrators may manage business contexts in Score.

Each business context may have zero-to-many roles associated with it (managed only by administrators). See Figure 3.

...

There are many ways to design the UI to show roles associated with a business context and to add/delete them. Figure 3 is just one example.

...

The built-in roles will be supported (end user, developer, admin) as Score_End_User, Score_Developer, and Score_Admin roles in Auth0.

...

1. 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. Context category: Tenant

   2. Context scheme: Tenant (based on 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 feature implementations do not 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. This should prevent two undesirable situations (just FYI):

      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 category 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 associated with at least one business contexts that are associated with one of the user’s roles.

...

1. has as least one Tenant context scheme value matching the user’s tenancy. (Accedia will need to implement restrictions.)

Logical process for determining what BIEs to show in

...

a BIE list

See https://oagiscore.net/profile_bie.

• For each BIE

  • For each of the BIE’s business contexts

    For each of the business context’s roles

    Is the user in that role

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

    • No: Show the BIE in the list.

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

      • Yes: Show the BIE in the list.

      • No: Don’t show the BIE in the list.

Concrete example

Score roles

...

Score role

...

• Admin + Developer

...

• Admin

...

• +

...

• End

...

• User

• Developer

...

Score_Developer

...

End User

• End

...

• User

Example tenants

...

Tenant

...

Auth0 role

...

...

• AgGateway

...

...

• ACME

...

• Brick

• HR Open Standards

...

Score_Tenant_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

...

• Mary can access all BIEs because she is in the Score role Admin+Developer. Users in the Score roles Admin+Developer or Admin+End User can see a Dev/Admin. Dev/Admins can access everything.

• Matt can only access:

  • BIEs in a business context

  associated with the ACME Brick tenant.

  • 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.Ross can only access

  • BIEs in a business context

  associated with the ACME Brick tenant or the AgGateway tenant, which in this example computes to be all of them.

Analysis about how this change could impact current on-prem users (and existing OAGi instances of Score), assuming we go with the business context (BC) approach

1. There is no difference between being admin or not being admin in term of the BIEs Access. So, it is okay to simply refer to Developer and End User here. But these have to be differentiated in the authentication server.

2. When current instances of Score get upgraded to a multi-tenant version, roles have to be assigned to existing business contexts. Here are to options to keep the current accesses to existing BIEs

   1. Business contexts that have no roles assigned are accessible by any Score role or tenant.

   2. Assume that Developer, Admin+Developer, End User, and Admin+End User can always access all BIEs even though these roles are not associated with business contexts.

   3. All existing business contexts will be assigned all four roles when making upgrade to the multi-tenant version.

   4. Apparently, approach (a) is simpler. And for convenience, we mighty assume (c) as well. I don’t see any issue with that at this point. It means that the current BIEs in OAGi instances will be accessible to all, but that can also be changed later on.

3. About the business contexts, currently anybody can manage business context. If the multi-tenant version restricts this to only Admin Developer or Developer, this can cause an issue with existing customers.

   1. Alternatives are:

      1. Make it an installation option to who can manage the BCs.

      2. Make an inform decision with current users. Maybe this is a best practice to limit BC management to only Developer role.

      3. Change the multi-tenant requirement to “Only Developer can manage BC/Role Assignment”. In other words, everyone is still free to create and manage the BC content itself but only Developer can assign roles to BCs. We have to think about BCs discard function, b/c right now anyone can discard BCs if there is no associated BIE - and this is likely still ok.

   2. Option (iii) seems simplest.

So this seems quite manageable.

Analysis between using Business Context & Role vs. using only Role to control BIE access

...

Using BC and Role

...

Using Role only

...

Pros

...

Offer multi-dimension control. I.e., can be made as if BIE accesses are managed by role alone. That is, a BC is created corresponding to each role and only that role. In this way, it is pretty much the same as using Role only.

...

Offer a level of aggregation to manage BIE Access rather than individual BIEs.

...

Cons

...

Have to always assign role to a BC, i.e., there is no role assignment automation. On the other hand, we can also implement a function to manage a default BC for a user account in the future.

...

Can automatically assign role selected by the current user to the BIE when it is created.

...

Have to manage access for each BIE.

Additional things to consider

...

Are all other user roles that are not Developer, Admin Developer, End User, and Admin End User considered subclasses of End User role? In other words, users in these roles inherit behavior of End User, e.g., they cannot create account, they cannot manage developer CCs, they can extend BIEs.

...

Note that if they can extend BIEs, it means that we have to also implement access logic on the CC side where they can manage only end user CCs. However, end user CCs have no BC assigned, so how to we infer access authorization? <serm>I couldn’t think of a nice and simple solution to this. The simplest thing to do, which sounds like a hack, is to do not allow BIE extension for users that are not End User or Admin End User. Another option is to inferred, roles associated with CCs from BIEs they are used in, but some EUCCs may not yet be used in any BIEs. Or we can say that if they are not used yet then only the owner can access it. </serm>. EUCCs logic also have to change in that only EUCCs with the same access authorizations can be used together, but what if the access authorizations change later on. This is getting pretty real complicated.

...

• • 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

...

• 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.

...