Understanding the Updated Identity and Access Management Controls

Prior to v1.31.0, ProKnow Identity and Access Management (IAM) was implemented via Workspaces, Roles, and Users. In v1.31.0, we introduced an updated set of IAM controls. If you started using ProKnow prior to the v1.31.0 release, this article will help you understand the differences between the two IAM systems and how your IAM entities were migrated to the new system. If you started using ProKnow after this release, the best way to learn about these new controls is by reading the Understanding Identity and Access Management article.

Resources

At the root of the new IAM system is a resource. There are six resource types: Organizations, Groups, Workspaces, Patients, Organization Collections, and Workspace Collections. Resources are organized into a hierarchy depicted in the diagram below.

Figure 1: Resource Hierarchy

A User will be able to perform an action on a resource if the User or a Group they belong to is assigned a Role that grants the required permission on the given Resource or one of its parent resources. Users, Groups, and Roles are discussed in more detail in the sections that follow.

Some resources like patients have subresources (DICOM objects, scorecards, etc.) that are not formally represented in the hierarchy. Access to these subresources is governed by assignments on the closest formal resource in the hierarchy. For example, access on the patient scorecards is governed by permissions on the patient resource, and access to users is governed by permissions on the organization resource.

The inherited nature of permissions allows you to effectively assign permissions for a given resource at multiple levels of the hierarchy, however, assigning the same role at different levels will have a different interpretation. For example, let's examine the various ways you might give access to a patient:

• You can assign the "Contributor" role on a single patient, which will give the user access to edit that single patient (and only that patient).
• You can assign the "Contributor" role on the workspace in which the patient belongs, which would give the user access to that patient, and all other patients in the same workspace.
• You can assign the "Contributor" role on the organization, which would give the user access to that patient, and every other patient in the entire organization (as well as a whole host of other resources and subresources).

The management of resource assignments is performed on the page specific to each resource. See the Managing Access page for more details.

Roles

In the previous version of the IAM system, Roles defined both the Resource and the Permissions on those Resources. Users would be assigned exactly one Role in the system, granting the permissions on the resources as defined in the Role.

In the new IAM system, the Permissions and the Resources have been decoupled, and Roles now refer to a set of permissions. In addition, Roles are no longer assigned directly to users. Roles are assigned to the Organization, a Group, or a User on a Resource.

Your organization will be populated with a set of system roles, which cannot be edited or deleted. These roles provide logical groupings of permissions and should be sufficient for most use cases. In general, custom roles for your organization will not be required.

Roles are managed on the Roles tab of the IAM module.

Groups

In the previous version of the IAM system, granting the same set of permissions to a set of users could be accomplished by assigning each of them to the same Role.

In the new IAM system, this can be accomplished by adding users to the same group and then assigning appropriate roles to the group on an appropriate set of resources. Note that users are automatically added to the root-level organization group. Organizations can also take advantage of the fact that membership flows upward to the parent groups. For example, if a user belongs explicitly to the root-level organization group and Group A.1, they are also a member of Group A:

Organization Group
|- Group A
   |- Group A.1
   |- Group A.2
|- Group B
   |- Group B.1
   |- Group B.2

Groups are managed on the Directory tab of the IAM module.

Users

In the previous version of the IAM system, users were managed on their own tab in the IAM module. Users may only be assigned to a single role, either a system role defined in their organization or a special private role defined just for that user.

In the new system, Users are managed alongside groups on the Directory tab of the IAM module. In addition, it is now possible to assign several roles to a user on a given resource (just like groups).

Examples

Use Case: Research Organization - Everyone Has All Permissions

Consider a small group of researchers with their own ProKnow organization. If each researcher should have full access to the organization, the permission setup is simple (see Figure 2):

• All users should belong to the special organization group at the root of the directory. Since all users are automatically added to this group, no configuration is required.
• Assign the "Owner" role to the "RGB Hospital Network" group on the "Organization" resource.

Figure 2: Entire Organization Has Full Access

Use Case: WorkspaceRead/Write Access

Consider an organization with two workspaces and two sets of users. One set of users should have read access to Workspace A and write access to Workspace B. A second set of users should have read access to Workspace B and write access to Workspace A. To achieve this in the old system, an administrator would have had to configure two custom roles: one for the first set of users with read access to Workspace A and write access to Workspace B and another for the second set of users with read access to Workspace B and write access to Workspace A. To achieve a similar setup with five workspaces and five sets of users, an administrator would have to create five distinct roles and assign the correct role for each user in the system.

In the new system, this setup can be simply achieved by creating a group for each set of users and then assigning the built-in roles "Reader" or "Contributor" to each group on each of the workspace resources as appropriate.

Use Case: Large Distributed Network

Consider a large distributed hospital network that wishes to keep their patient PHI private. Each hospital has their own IT administrators who need the ability to manage permissions for their organization independently. However, the hospitals also wish to share patient contouring responsibilities across the network. The group directory for this kind of ProKnow organization might look like this:

RGB Hospital Network
|- Network Administrators
|- Red Valley Cancer Center
   |- Physicians
   |- Physicists
   |- Dosimetrists
   |- Administrators
|- Green Plains Cancer Center
   |- Physicians
   |- Physicists
   |- Dosimetrists
   |- Administrators
|- Blue Mountain Cancer Center
   |- Clinicians
   |- Administrators

Each user in the organization should be added to their appropriate subgroup. Remember that a user can belong to more than one group. A physicist, for example, might also fulfill the role of hospital administrator. In that case, the physicist would belong to both the Physicist and Administrator group for their hospital. Also, notice that Blue Mountain Cancer Center has defined their groups a bit differently than the others, defining a single group for their clinicians rather than separate groups.

Now, let's suppose that the organization also defines a workspace for the clinical patient data for each hospital:

• Red Valley
• Green Plains
• Blue Mountain

With this configuration, the organization could configure their roles as follows.

• The "Network Administrators" group should be given the "Manage Access" role on the "Organization" resource. This will allow the users in that group to create subgroups and change group memberships across all groups within the organization. This is depicted in the screenshot below (see Figure 3).
• The "Administrators" group under each cancer center group should be given the "Manage Access" role on the hospital group resource. This will allow the users within the "Administrators" group to create subgroups under the hospital group and change group membership for the hospital group and all subgroups as needed (see Figure 4).
• Roles on the workspaces should be defined as follows (see Figure 5 for an example using the "Red Valley" workspace):
  • Assign the "Red Valley Cancer Center" group the "Contributor" role on the "Red Valley" workspace.
  • Assign the "Green Plains Cancer Center" group the "Contributor" role on the "Green Plains" workspace.
  • Assign the "Blue Mountain Cancer Center" group the "Contributor" role on the "Blue Mountain" workspace.
  • Assign the "Green Plains Cancer Center" and "Blue Mountain Cancer Center" groups the "Contourer" role on the "Red Valley" workspace.
  • Assign the "Red Valley Cancer Center" and "Blue Mountain Cancer Center" groups the "Contourer" role on the "Green Plains" workspace.
  • Assign the "Red Valley Cancer Center" and "Green Plains Cancer Center" groups the "Contourer" role on the "Blue Mountain" workspace.

Figure 3: Access Defined on the Organization

Figure 4: Access Defined on the "Red Valley Cancer Center" Group

Figure 5: Access Defined on the "Red Valley" Workspace