Read restricted Configuration

By default, WebAPI assumes all users are granted read-access to entities. Write permission is granted to the entity creator, and also can be assigned by the creator to other users.

As of 2.14, there is an optional enhancement that allows read permission to be restricted so that only users with read access to a given artifact can view them. More information and discussion of this enhancement can be found in issues 2222 and 2300 and pull request 2301.

Here are instructions for organizations that would like to enable this enhancement:

Preparation:

• It is recommended that organizations only use this feature for a completely fresh Atlas/WebAPI installation. For organizations with an existing Atlas/WebAPI installation, do not make this change without careful consideration. If your organization decides to proceed, you should inform users well in advance that you are planning to enable this change and that it will have the following effects on their workflow:
  • An admin will have to remove all roles from each non-admin except their user role, any roles that give them access to the CDM sources (e.g., roles with names like "Source User (<source key in the 'source' table>)", and a role assigned called 'read restricted Atlas users' (role ID 15) that removes global read access while still granting permission to view the listings returned by the concept sets, cohort definitions, characterizations, cohort pathways, incidence rates, and prediction tabs (see pull request 2316).
    • Note that the migration script creates the 'read restricted Atlas users' role for the WebAPI 2.14 release was incomplete with respect to permissions. A migration script that corrects the issue is currently available as a pull request: https://github.com/OHDSI/WebAPI/pull/2342/
    • Users with the role will only see artifacts they have explicit READ access to in the listings returned by the concept sets, cohort definitions, characterizations, cohort pathways, incidence rates, and prediction tabs.
    • If user 1 shares a link to artifacts that the user created with user 2 who has the role, user 2 will not be able to see that artifact unless user 1 or an admin has granted them READ access to it
    • If user 1 with the role had created an artifact with id 'x' prior to the configuration change that enabled read restriction, user 1 might not be able to access the artifact until an admin grants them access specifically the artifact.
    • Note that, if your users with the new 'read restricted Atlas users role' are unable to access the 'Search' functionality in Atlas, it is probably because they do not have the role that give them access to the CDM source (e.g., roles with names like "Source User (<source key in the 'source' table>)."
  • Users with the role may give other users READ access to artifacts that they own and have WRITE access to using the grant permission feature in Atlas (the lock icon that appears when a user opens a given artifact).
    • Note: The organization may not want users to have this ability. If so, the organization may shut this feature off in Atlas config-local.js by adding the line configLocal.enablePermissionManagement = false;.

WebAPI configuration:

• in your WebAPIConfig/settings.xml add the config <security.defaultGlobalReadPermissions>false</security.defaultGlobalReadPermissions>

Atlas configuration (optional):

• If you want Atlas to hide the 'lock' icon so that the user cannot edit READ and WRITE permissions when viewing concept sets, cohort definitions, and other artifacts:
  • in js/config-local.js add configLocal.enablePermissionManagement and set this equal to false

Known issues:

• If read permissions are filtered, users will want to make some artifacts public. This is not possible in Atlas 2.14. See the discussion about this topic in issue 2236.
• WRITE permissions are not implemented as READ+WRITE permissions so, if a user with the restricted read permission mentioned above has WRITE permission to an object, they will not see this object in the list unless granted READ permission. This is expected behavior at this time but needs to be noted (see issue 2322)
• If an organization has enabled read access restrictions but still has users with had the Atlas Users role, it is possible that a user with the Atlas Users role will can see any artifact via direct link (see issue 2321). This is expected behavior when the organization has not followed the recommendation above of removing all roles from each non-admin user except their user role, any roles that give them access to the CDM sources, and a role assigned called 'read restricted Atlas users'.
• Similar to the prior listed issue, If an organization has enabled read access restrictions in an existing Atlas/WebAPI installation, but not followed the recommendation above of removing all roles from each non-admin user except their user role, any roles that give them access to the CDM sources, and a role assigned called 'read restricted Atlas users', then a aser with 'read restricted Atlas Users' role will not be able open their own objects created prior to the configuration change (see issue 2323).
  • To explain more clearly, in a fresh installation, this behavior does not happen because the WebAPI ensures that READ permission for each artifact created by the user is added to their user role in the security database. In an installation where the new enhancement is retrofitted, the WebAPI might not have granted the user role READ permission to each of the artifacts they created (because it was just assumed to be present in older version of WebAPI). So, the admin needs to do this explicitly.
    • Example: A user with user_id 1111 in the sec_user table of the WebAPI security database who created cohort definition ID #18 prior to the change to restrict read access. The admin needs to:
      1. Find the users role ID in the sec_user_role table, let's say it is 2222
      2. Find the get, info:get, and version:get permission records to cohort #18 in the sec_permission table
      3. Execute, within a transaction, an insert into the sec_role_permission table to add the three permissions above to the user's role

                -- SQL Code example:
                start transaction;
                insert into ohdsi.sec_role_permission (role_id, permission_id)
                with perm_ids as (
                  select id as permission_id
                  from ohdsi.sec_permission sp 
                  where sp.value in ('cohortdefinition:18:get','cohortdefinition:18:info:get','cohortdefinition:18:version:get')
                )
                select 2222 as role_id, permission_id
                from perm_ids
                ;
                -- IF NO ERRORS
                commit;