Authorizing Privileges on a Protection Element

This page explains how to authorize users to perform an operation on a protection element by working through a detailed scenario. There are a number of steps to this, starting with ensuring that the protection element exists.

	Contents Ensuring that a Protection Element Exists Protection Groups Roles User Groups Permissions

Ensuring that a Protection Element Exists

A protection element is an abstraction used by the CSM authorization model to make the authorization model useful for all kinds of applications. Rather than model authorizations for operations on application-specific entities, CSM models authorizations for operations on protection elements. It is the responsibility of services and applications that use the CSM authorization model to determine a relationship between application-specific entities and protection elements.

Though CSM defines the use of protection elements in abstract terms, this is a concrete example about how to manage protection elements used for instance-level authorization. We will describe protection elements that authorize people to read the contents of objects whose classes are associated with CSM filters.

Before reading the actual steps for doing this, you should be familiar with the mechanics of managing protection elements. You should also be familiar with the rules that the CQL_CSM library uses to interpret the values of fields in protection elements.

In this scenario, we want to authorize the value 16 for people to access objects associated with a filter whose target class is org.cvrg.domain.Study and whose attribute is id. This calls for a protection element whose Object Id field has the value “org.cvrg.domain.Study”; whose Attribute Name field has the value “id”; and whose Attribute Value field has the value “16”.

We begin by determining if the needed protection element already exists. We navigate to the Access Control Management window's Protection Elements tab. We enter “org.cvrg.domain.Study” in the Object Id field and click on the Search button. A list of protection elements appears whose Object Id field contains “org.cvrg.domain.Study”.

We see that there is an existing protection element that contains the needed values. Its name is “Big Study (16)”. This is the protection element that we will use.

If the protection element did not already exist, we would have created it by clicking on the Create button, waiting for the Create Protection Element dialog to appear and then filling it in as shown below.

Now that we have the needed protection element, we need to authorize users to read the protection element. The CSM authorization model does not allow us to directly authorize users to perform an operation on a protection element. Instead, the CSM authorization model allows us to authorize users to perform operations on a protection group. Protection groups may contain protection elements and other protection groups. When we authorize a user to perform an operation on a protection group, the user is authorized to perform the operation on all protection elements that are directly or indirectly members of the protection group.

Our next step will be to make the Big Study (16) protection element a member of an appropriate protection group.

Protection Groups

A protection group is a collection of protection elements and other protection groups. Before you can authorize someone to perform an operation on a protection element, the protection element must be part of a protection group.

In this example we will create a protection group and add a protection element to it. Before reading the actual steps for doing this, you should be familiar with the mechanics of managing protection groups.

At the beginning of this scenario, we have a protection element named Big Study (16) that we want to authorize users to read.

We navigate to the Protection Groups tab of the Access Control Management window. We click on the search button to see a list of the currently defined protection groups.

Looking at the list of existing protection groups, we do not see any existing protection group with a name that sounds like it might already contain the “Big Study (16)” protection element. We decide to create a new protection group.

We click on the Create button. The Create Protection Group dialog appears.

In the Name field we enter “Big Study Protection Group” and click on the create button. The Create Protection Group dialog disappears. The new protection group appears in the list of protection groups.

Having created the Big Study Protection Group we now need to make the Big Study (16) protection element a member of the Big Study Protection Group protection group. To do this, we begin by selecting Big Study Protection Group in the list of protection groups.

Next, we search for the protection element that we want to add to the protection group. We enter “Big*” in the Name field, which will match all protection elements whose name begins with “Big”. We click on the Search button in the Search for Protection Elements area on the bottom of the window. The one protection element that matches the search term appears.

We click on the protection element in the list to select it. The arrow button for adding the protection element to the protection group becomes enabled.

We click on the arrow button to move the selected protection element into the protection group.

We have now successfully created the Big Study Protection Group protection group and added the Big Study (16) protection element to it.

Our intention for the new protection group is to authorize some users to read it. Before doing this, we want to take a look at what roles are defined.

Roles

A CSM role is a set of privileges. The interpretation of privileges is up to the application or service that is using the CSM authorization model. Most privileges correspond to the names of operations to be performed, such as READ, WRITE or CREATE.

In the following paragraphs, we work through a concrete example of ensuring that a role exists that contains just a privilege named READ. Before working through this example, you should be familiar with the mechanics of managing roles.

In this scenario, we want to authorize users to read data in a data service that uses the CQL_CSM library's replacement CQL processor. This authorization will be just for reading data, so we will want a role that just includes a privilege that means a user is authorized to read data.

Both the CQL_CSM library's replacement CQL processor and its CQL pre-processor look for a privilege named READ. What we want to accomplish in this exercise is to ensure that there is a role that includes just the READ privilege and no other privileges.

We begin by navigating to the Access Control Management window's Roles tab. We click on the search button. A list of the existing roles appears.

We see that there is a role named Reader which sounds like what we want. We click on the Reader role to select it. Lists of the privileges that do and don't belong to the Reader role appear.

We see that the Reader role has the READ privilege and no other privilege, so the Reader role is the one we want to use.

If the Reader role did not already exist, then we would have to create it or a similar role. There are two steps to creating a role. First we create the role itself, then we set the privileges that go with the role.

The process of creating a role begins with clicking on the Add Role button. After clicking on the Add Role button, the Create Role dialog appears. We fill it out like this:

After filling out the Create Role dialog, we click on its Create button. The dialog disappears and the Reader role appears in the list of roles on the Roles tab.

To add the READ privilege to the Reader role we click on the READ privilege to select it in the list of available privileges.

We click on the left pointing button to move the READ privilege from the list of available privileges to the privileges that are in the role.

Those are all of the steps that we would have had to follow to create the Reader role, assuming that the READ privilege already existed. If the READ privilege did not already exist, you would need to create it using the mechanism for managing privileges.

Having created the Reader role, you can now use it to authorize users to read things.

User Groups

It is usually more convenient to create a single authorization for a group of users than it is to create multiple authorizations for each of multiple users. To support this convenience, the CSM authorization model allows you to define groups of users and then use a group as the subject of an authorization. There are two kinds of groups that you can define:

• Local Groups
  Local groups are kept in CSM database tables and completely managed through the same administrative interface as the rest of the CSM authorization model. If the groups that are defined will only be used for security for the same instance(s) of the same application as the rest of the CSM authorization model, then local groups are a good choice. If you want common group definitions to be shared by different services or multiple instances of the same service, then you should consider using Grid Grouper groups.
  
  
• Grid Grouper Groups
  Grid Grouper groups are defined and managed by an instance of the Grid Grouper service. CSM, through the CSM Service is able to use groups defined by Grid Grouper. When you create a CSM link to a Grid Grouper group, the CSM service gets the group definition from the specified gridGrouper instance and stores it in the local CSM database tables. The CSM service also receives updates of linked group definitions and updates the CSM database tables accordingly.
  
  Grid Grouper groups have the advantage that there are easily shared by multiple services or multiple instances of a service. However, they may be more difficult to administer, since you will need to have the administration done by someone who is a Grid Grouper administrator. Also, there may be a delay between the time that a group definition is updated in Grid Grouper and the time that the group definition is updated in the local CSM database tables.

In the following paragraphs, we will work through a scenario that involves linking CSM to a Grid Grouper group. Before working through the details of this example, you should be familiar with the mechanics of managing groups of users.

This example will consist of linking CSM to an existing Grid Grouper managed group named Big Study that will be used to authorize users to access information about a clinical trial being managed by an application called OpenClinica. We begin this process by navigating to the Access Control Management window's Groups tab.

We click on the Link Group button. The Link Remote Group dialog appears.

To find the information we need to identify the remote Grid Grouper group Big Study, we click on the Find button. The Select Group dialog appears.

Because the CSM UI is configured to work with only one instance of Grid Grouper, the correct instance of Grid Grouper is automatically selected. The tree of group definition names is loaded from the Grid Grouper instance and displayed in the bottom half of the dialog.

We expand the tree and navigate to the Big Study group. We select the Big Study group.

We click on the Select Group button. The Select Group dialog disappears. The Link Remote Group dialog's Grid Grouper field is filled in with the URL of the Grid Grouper instance that was selected on the Select Group dialog. The Remote Group Name is filled in with the full name of the group that was selected on the Select Group dialog.

We enter Big Study Investigators in the Local Group Name field. This is the name we will use to refer to this group within CSM.

We click on the Link Remote Group button. The Link Remote Group dialog disappears. We see a notification that linking the remote group was successful.

We click ok the OK button to dismiss the notification that linking the remote group was successful. The notification disappears. We see that the Access Control Management window is not updated to reflect a newly linked group.

We click on the Search button and the Access Control Management window is updated to show the newly linked group.

Permissions

CSM allows the creation of permissions that authorize users to perform the operations implied by a specified role on protection elements that belong to a specified protection group. In the following paragraphs, we will work through an example of this.

Before working through the example you should be familiar with the mechanics of managing permissions.

The scenario for this example is that you want to create a permission to authorize a group of users named Big Study Investigators to have the privileges for the role named Reader for the protection elements that belong to the protection group named Big Study Protection Group.

Begin by going to the Permissions tab of the Access Control Management window.

Make sure that the selected value in the Search Type field is Group. To select a group, click on the Find button. The Select Group dialog appears.

Since we do not have many groups already defined, we just leave the Group Name field blank and click on the Search button. Big Study Investigators appears in the bottom part of the dialog.

We click on Big Study Investigators to select it. We click on the Select button. The Select Group dialog disappears. The Group field in the Permissions tabs is filled in with the name of the group we selected. We click on the Search button to see if there are already any existing permissions associated with Big Study Investigators.

We see that the permission we need does not exist. We click on the Create button to create the permission. The Create Permission dialog appears.

We make sure that the value selected for the Permission Type field is Group.

We click on the Create Permission dialog's Find... button next to the Group field. The Select Group dialog appears. We use the Select Group dialog to select the Big Study Investigators group and then click on the dialog's Select button. The Select Group dialog disappears. The Create Permission dialog's Group field is filled in with Big Study Investigators.

We click on the Find... button next to the Protection Group field. The Select Protection Group dialog appears.

Since we know that there are few protection groups currently defined, we leave the Select Protection Group dialog's Protection Group Name field blank. We click on its Search button. A list of protection groups appears in the bottom half of the dialog.

We click on Big Study Protection Group to select it. We click on the Select button. The Select Protection Group dialog disappears. The Create Permission dialog's Protection Group field is filled in with Big Study Protection Group.

The final step in creating this permission is to add the Reader role to it. We click on the Reader role to select it.

We click on the left-pointing button to move the reader role to the Granted Roles list.

We click on the Create button. The Create Permission dialog disappears. We see a notice that the permission has successfully been created.