Page Comparison

ld

We have been looking at three related pieces of work:

...

Secured objects/scopes

* = this is an association, the object identifier is going to be the first part of the association, so for example, an organization study object is identified by its organization. Study participants permissions are identified by the

...

Model/Association/Verb

...

Permission

...

Meaning

...

Organization

...

userId ∈ {organization:orgId view}

...

Can view information about the organization.

...

userId ∈ {organization:orgId edit}

...

Can edit the organization

...

userId ∈ {organization:orgId admin}

...

Can edit permission for the organization

...

SponsoredStudies *

...

userId ∈ {sponsoredstudies:orgId list}

...

Can see the studies sponsored by the organization

...

Members *

...

userId ∈ {members:orgId list}

...

Can see the members of an organization

...

userId ∈ {members:orgId admin}

...

Can create/add/remove members

...

Assessments *

...

userId ∈ {assessments:orgId list}

...

Can view the assessments of an organization

...

Study

...

userId ∈ {study:studyId view}

...

Can view a Study (not its participants).

...

userId ∈ {study:studyId edit}

...

Can view or edit the Study

...

userId ∈ {study:studyId admin}

...

Can edit permissions for the Study

...

Study PI *

...

userId ∈ {studypi:studyId edit}

...

Can move the study from design to recruitment.

...

StudyParticipants *

...

userId ∈ {participants:studyId list}

...

Can view a list of AccountSummaries in this study

...

userId ∈ {participants:studyId view}

...

Can view StudyParticipant

...

userId ∈ {participants:studyId edit}

...

Can view or edit StudyParticipant

...

userId ∈ {participants:studyId admin}

...

Can create accounts and enroll/withdraw them from the study.

...

Assessment

...

userId ∈ {assessment:guid view}

...

Can view an assessment

...

userId ∈ {assessment:guid edit}

...

Can view or edit an assessment

...

userId ∈ {assessment:guid admin}

...

The basic permission types are:

Some of these permissions can be powerful. For example, {participants:studyId edit} has the power to create accounts and enroll them in a study, or withdraw them later.

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 roleaccessLevel; // "admin", "developer"
  String objectTypeentityType; // "study", "organization", "app", "system"
  String objectIdentityId; // "studyId", "orgId", "appId"
  
  // Suggested toString() descriptor (implicitly scoped to an app):
  // "2rkp3nU7p8fjUTDVIgjT6T ∈ {organization:sage-bionetworks admin}"
}

public// enum ObjectTypeEach type relates to a specific entity and its ID (indicated in the constructor)
public enum PermissionType {
  ASSESSMENT (ASSESSMENT),
  STUDY (STUDY),
  ORGANIZATION (ORGANIZATION),
  SPONSORED_STUDIES (ORGANIZATION),
  MEMBERS (ORGANIZATION),
  ASSESSMENTS (ORGANIZATION), // ASSESSMENT_LIBRARY?
  STUDY_PI (STUDY),
  PARTICIPANTS (STUDY);
}

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

...

interface PermissionsService {
  Set<Permission> getPermissionsForUser(String appId, String userId);
  Permission addPermission(Permission permission);
  void updatePermission(Permission permission);
  void removePermission(Permission permissionspermission);
  Set<Permission> getPermissionsForObjectgetPermissionsForType(String appId, ObjectTypePermissionType 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 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, ObjectTypePermissionType type, String objectId, Role... roles);
}

...

...

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 will need to be maintained for older APIs. New APIs including assessments, all the /v5/studies/* APIs, will solely use the new permissions system. Therefore, we will not map existing roles into the permissions table. We will migrate the study-scoped 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.

Role to Permission Mapping

This mapping is necessary for steps 2 and 3 in migration. Each role needs to be mimicked by permissions.

Roles manage access to studies and assessments through organization membership. The “sponsored studies” and “assessment library” permissions similarly grant access to studies and assessments based on organization. So the individual “study” and “assessment” permissions should be unnecessary for migration.

The “participant” permission is more complicated because it is handled by individual study. Developers and Study Designers only have access to test accounts. Researchers and Study Coordinators have access to participant data. So mimicking the role means granting “participant” access to each study in their organization.

Multiple organization membership

...