We have been looking at three related pieces of work:

1. Refactoring our account system to separate participants and administrative users;

2. Implementing more flexible, role-based authorization over domain objects (like studies);

3. Allowing users to be assigned to multiple organizations.

In brief, these are mostly separate pieces of work, but we believe #1 should happen before further integration with Synapse or any other external accounts management system, and #2 should happen before #3, so we don’t have to add functionality to organizations that we would just then remove. Doing #1 first might also make #2 easier to implement, but it is not absolutely necessary.

Separate participant and administrative account management

The business logic behind participant accounts has always been substantial (verification, consent, anonymization), but recently our requirements for administrative accounts have grown as well. Currently logic for both kinds of accounts is intermixed, making any additional work to either kind of account a higher risk than it needs to be.

Here are the current dependencies between our accounts, authorization, and consent classes:

This makes it difficult to talk about changes to the management of accounts, even for something like authorization. Here is one aspirational model where we separate Synapse-managed accounts and participant accounts, so that all the business logic around participants is separated from our code to manage admin accounts. Basically “Account" would refer to an administrative account and "Participant" would refer to a participant account most places in our code. (An alternative is to create a new thing, like AdminAccount, for the admin accounts):

There would be backwards-incompatible consequences to this refactor. The /v3/participants APIs could no longer be used to create and manage administrative accounts. I don’t know who uses these for that purpose, at least the Bridge Study Manage would need to revise the UI it has to list all admins/users in one giant list (currently under the legacy panel). That API is still useful, but it would only return true participant accounts.

Notes on refactoring…

General

• Explicitly mark administrative accounts before we migrate roles, because right now that's the way we determine these kind of accounts. We don’t want administrative accounts to turn into participant accounts if someone (by mistake or otherwise) removes the roles from the account.

AccountDao & AccountSecretDao

• In the refactor above, a number of services can directly use AccountDao rather than AccountService. AccountDao and AccountSecretDao are basically fine as is, but we could write faster custom queries to return things like ID and health code than we are currently doing in the service classes.

ParticipantVersionService

• Should monitor changes to the Accounts table that are done through ParticipantService, not AccountService.

ConsentService, EnrollmentService

• AccountService -> AccountDao

AccountService & ParticipantService

• These two could use a common abstract parent class. For example, deleteAccount() and deleteParticipant() would share a lot of code in common. Other places they will be pretty different (e.g. only AccountService needs to enforce role change logic, only participant service needs to deal with enrollment scenarios, etc.)

AccountService

• move authenticate, changePassword, reauthenticate, deleteReauthToken, verifyChannel to the AuthenticationService.

• Event services should not be used in AccountService, they should be used in ParticipantService;

• ParticipantVersionService: should be used in ParticipantVersionService

• any attempt to manipulate participant accounts through this service should fail immediately with a bad request exception;

ParticipantService

• AccountService -> AccountDao

• Any code related to roles and/or organizations can be removed to AccountService;

• any attempt to manipulate admin accounts through this service should fail immediately with a bad request exception;

• updateIdentifiers: authenticate in the controller as part of the security check so you can take these auth methods out of AccountService and ParticipantService. Also this method is more likely useful on AccountService (arguably we can just allow administrators to change participant’s phone and email address).

Auth: AuthenticationService, AccountWorkflowService, OAuthProviderService

• These are all related and could be combined, except that it would make an unwieldy service. Maybe we could have a front controller that delegates to a set of implementation classes so external classes only deal with an AuthenticationService, but we're not maintaining a monolith.

• AccountService/ParticipantService → AccountDao in all three services

UserAdminService

• Fine as is (a crazy service to make integration testing palatable).

AccountController

• add paginated API to retrieve admin accounts in the app (across all organizations…organizations have a membership API that most of our external users should be using);

• access to these methods would require app:admin or system:superadmin powers (see below);

UserManagementController

• it may be simpler and easier to create enrollment records directly in the account for testing purposes. This would remove the consent service and the enrollment service references;

• An AccountService/ParticipantService base class should delete from all those other services, so we don't have to reference userAdminService just to properly delete an account.

Expanded permissions model

We’re seeking a permissions model that will cover our current security capabilities while tackling new use cases, such as the ability to manage access to studies.

• The authorization model will be role-based, assigning a role vis-a-vis a specific target model (we’ll call this a “permission”);

• These new permissions will be a separate table, not an association to an Account or any other record in the system…this is easier to graft onto the existing system, but it does mean that permissions won’t be deleted by the database when their associated user or model object is deleted (due to the use of non-SQL databases, this is often true in our system);

• Organizations will principally be a means to communicate who can see whom in a multi-tenanted application. Accounts will be assignable to multiple organizations. Migrated accounts will be given permissions to the sponsored studies of that organization, and then going forward, further permissions will have to be added on a case-by-case basis;

  • Another option: a person who is a developer in an organization can create a study, which is automatically sponsored by the organization.

  • A person creates a study and owns it and absolutely no one else can see it until it is sponsored or shared with others.

  • Organizations continue to transitively give their members a role that allows them to see the organization’s sponsored studies. They could then ask to have more specific roles vis-a-vis one of those studies.

• Bridge roles are hierarchical (in behavior, not in implementation). Generally a user should have only one role vis-a-vis a model object. For example, being a STUDY_DESIGNER implies that you can read information about studies, like the AUDITOR role. Every study designer does not also have to be an auditor. PI_AGENT could be an example of an exception to this.

  • App-scoped developer and researcher should no longer have study-scoped permissions;

  • App-scoped admins can still probably do anything within their app;

  • System-scoped admins can still do anything in any app;

  • Otherwise, objects do not have any hierarchy (roles over an app do not imply roles over a study).

Use Cases

Secured objects/scopes

Note that membership in an organization is also directly modeled in the database right now via the Account.orgMembership field. If we continue to model this in the database, it'll become an associative table and that association could specify the roles you gain as a member of the organization—however no one is asking for this so I don't intend that we will do it.

Implementation

We will introduce a flat table of Permission records that can be easily retrieved by user or by target model object:

public class Permission {
  String guid; // synthetic key makes create/add/update APIs easier
  String appId; // most permissions except system-wide, and usually implicit
  String userId;
  String role; // "admin", "developer"
  String objectType; // "study", "organization", "app", "system"
  String objectId; // "studyId", "orgId", "appId"
  
  // Suggested toString() descriptor (implicitly scoped to an app):
  // "2rkp3nU7p8fjUTDVIgjT6T ∈ {organization:sage-bionetworks admin}"
}

For APIs that have to display permissions, the appId/userId can be replaced with an AccountRef object, similar to the EnrollmentDetail object.

The service (along with a method to integrate with Spring Security):

interface PermissionsService {
  Set<Permission> getPermissionsForUser(String appId, String userId);
  Permission addPermission(Permission permission);
  void updatePermission(Permission permission);
  void removePermission(Permission permissions);
  Set<Permission> getPermissionsForObject(String appId, ObjectType type, String id);
  // this delete cannot be cascaded by the database and must be done manually.
  void deletePermissions(String appId, ObjectType type, String id);
  
  /** Spring security will need a very focused method to check, for a 
    * given user and a given object, does the user have any of the required 
    * roles to perform the request. This method can fudge things like 
    * app-scoped permissions, too.
    */
  boolean isAuthorizedAs(AccountId accountId, ObjectType type, String objectId, Role... roles);
}

There will be top-level APIs to change permissions. Creating an object that is managed with permissions will always make the creator the administrator of that object:

Spring Security

Spring security has nice support for annotation-based authorization constraints. I would suggest we switch to it and secure the system at the controller layer by annotating our controller methods. Spring provides an expression language we can use to declare our constraints, and we can even implement new methods in that constraint language, so that Spring delegates to our own code to answer authorization questions. It would allow new developers to work with a technology that they have seen before, and that is documented.

Using Spring security for authorization (not authentication, at least initially) we would do the following:

1. In a filter, create a caller's Authentication object and put it in Spring Security's SecurityContext (exactly like what we've been doing with our own RequestContext; we’d store the user’s ID and app ID);

2. Add authorization annotations to all of our controller methods.
   We can basically do our security checks in these annotations, e.g. @PreAuthorize("permit('developer', #studyId)") - permit a developer for the study ID (taken from the method’s parameters) to access the controller method. Or @PostAuthorize("returnedObject.ownerId == authentication.orgMembership") to check rules against the object being returned from the method. Because we can implement custom functions in the evaluation language, we can carry over our specific business logic. Later we can hook in other authorization systems very cleanly this way.

3. Remove our own static method call checks in AuthUtils. Eventually consider if we can remove RequestContext since it is 90% of the time being used to do authorization checks.

Migration

Existing roles can be expressed in the new permissions table in order to make the same kind of authorization checks. This can be done independently of allowing users to be in multiple organizations. For every administrative account in the system, we’d want to create entries based on their current roles:

The steps would be:

1. Add the permissions table, service, APIs, completely separate from existing security so they are completely functional;

2. Create bridge code so that roles and organization membership changes are mirrored in the permissions table (but not vice versa?);

3. Migrate all existing account roles to the new permissions tables. Changes made at any time after the migration should also make it to the permissions tables, which still cannot be used;

4. Annotate our controllers with the new permissions;

5. Remove old code checking permissions;

6. Switch over to use the new permissions apis rather than account APIs to manage permissions (probably by throwing errors if roles are changed on an account).

7. Remove bridge code;

8. Remove roles from accounts;

9. Remove code that is granting permissions to studies as a result of organization membership, which is a large external change that will need to be documented and supported in existing tools.

Multiple organization membership

Introduce a Membership associative table between Accounts and Organizations, and migrate the existing orgMembership value to this table. The table should be a simple associative table as roles are managed separately. But when we need to retrieve the list of members, or the organizations a person belongs to, it’s the object model we will examine.

Externally the biggest change to the Organizations API would be that adding or removing a person from an organization would not automatically change their one and only membership.

Questions

• We could design the permissions table so the objects are cascade deleted when object is deleted, otherwise it will need to be done manually (a method we must call).

• Assessments are owned by organizations, but what does that mean going forward? I would think all organization members can read or list the organization’s assessments, but can you be a developer vis-a-vis an assessment? Who would assign that (presumably the organization administrator)? Can an assessment itself have an admin?

• Can we manage permissions for “entities of concern” in Synapse, specifically projects and access teams? It would appear we need to follow an authorization model that’s close enough to Synapse’s that we can translate changes in the Bridge paradigm to meaningful changes in Synapse, and vice versa (at least for the entities we directly work with).

• Can we build an invitation system that uses Synapse to send the messages, since we won’t have email addresses for Synapse accounts? It seems like we will eventually want the same invite-and-accept functionality for joining organizations, studies, etc. that we see in Synapse. Actually this goes for things like warnings about participants who are out of adherence (and it’s out of scope but came up in this design discussion).