Bridge v2 authorization model

Separate participant and administrative account management

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:

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

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.

Use Cases

Secured objects/scopes

Organizations

“Teams” in Synapse impart an identical set of permissions to a project for a set of users. “Organizations” in Bridge are a scope for manipulating users, since our app is multi-tenanted. The roles related to organizations:

Note that membership in an organization is also directly modeled in the database right now via the Account.orgMembership field, and will be moved to an associative table. We may not need a “member” role though it may be more convenient.

Studies

Individuals can be given specific roles vis-a-vis a study.

App/System

These are legacy roles but there are still many APIs that require one of these roles, particularly around configuring an app:

Implementation

Using Spring Security

We’re reimplementing a lot of the functionality of Spring Security’s authorization support. It might be desirable to switch over rather than further implementing a custom solution. We need a table of permissions that can be used to answer the framework’s authorization questions.

class Permission {
  String guid; // natural key makes create/add/update ambiguous
  String userId;
  String role;
  String objectType;
  String objectId; 
  
  // Object ID may need to be compound
  void setStudyObjectId(String appId, String studyId) {
    this.objectId = appId + ":" + studyId;
  }
}

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, but we'd probably store the caller's permissions);

2. Add authorization annotations to all of our controller methods.
   Spring has many choices, including annotations that will take expression languages and security check methods that we can write ourselves. I like that option a lot. So 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 parameters) to access the controller method. But because we can implement that "permit" method, we could also allow app developers, admins, and superadmins to pass this test, as we do now.
   Another approach is to create custom annotations that bundle complicated expression rules (e.g. @IsDeveloper could do all of the above).

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

There will be top-level APIs to change permissions:

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:

We’d need to update both representations of roles in both places (as part of accounts and part of permissions), move over to authorizing requests using the permissions table, and then remove the bridge code and finally, delete the AccountRoles table.

Multiple organization membership

Once we have a permissions table, we can implement accounts being in multiple organizations. The utility of this construct will be lessened (because people can be permitted to act directly against a study) but it may still be important for the future.