Bridge v2 authorization model

Use Cases

Use Case
New admin account created with a sandbox in which studies can be created/edited that are not visible to others
“Sandbox” can be converted to real study, with additional users in specific roles for that study
Study is extended by creating a new study
Add someone to a study’s administration team
Remove someone from a study’s administration team
Create similar authorization model for assessments	We should be able to expand it to other things than studies, because it seems likely we’ll encounter something else that needs finer-grained authorization.

Requirements

Permissions changes should register for users without them having to sign out and sign back in again (if cached they need to be separate from the session);

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:

Role	Scope
Administrator	Organization	Can list, view, add and remove people from an organization. Can they edit an account in the organization Can list studies sponsored by the organization
Member	Organization	Can list people in the organization Can list studies sponsored by the organization

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.

Roles	Scope
Developer	Study	Can edit the configuration of the study and its schedule.
Researcher	Study	Can list, view, edit, delete, enroll and unenroll accounts in the study.
Governance	Study	Can move the study into a production stage, and can view the data being exported to a project in Synapse. User must be a validated Synapse user.
Admin	Study	Can do anything related to a study or its participants, and they can change users associated to the study or their roles in that association.

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

Roles	Scope
Developer	App	Can access many APIs for the configuration of an app and related resources like app configs.
Researcher	App	Can see all accounts in the system regardless of organization or study boundaries.
Admin	App	Can call any API in the scope of the account’s app.
Worker	Global	Can access APIs that specifically allow the worker to call across app boundaries without switching applications first.
Superadmin	Global	Can do anything in any app, study, or organization.

Implementation Considerations

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;
  }
}

There will be top-level APIs to change permissions:

Method	URL	Description
GET	/v1/permissions/{userId}	Get all permissions for a user.
GET	/v1/permissions/{objectType}/{objectId}	Get all permissions for an object like organization, study, or app.
POST	/v1/permissions	Create a permission for a specific object and user. Caller must be an admin for the object. Returns the object with a GUID.
POST	/v1/permissions/{guid}	Update a permission (caller must be an admin for the object).
DELETE	/v1/permissions/{guid}	Remove a permission for an object (caller must be an admin for the object).

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:

Old role	New role
DEVELOPER	APP DEVELOPER
RESEARCHER	APP RESEARCHER
STUDY_DESIGNER	STUDY DEVELOPER
STUDY_COORDINATOR	STUDY RESEARCHER
ORG_ADMIN	ORGANIZATION ADMIN
ADMIN	APP ADMIN
SUPERADMIN	SYSTEM ADMIN
WORKER	SYSTEM WORKER

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.