Authorizing Instance-Level Access

This page explains how to authorize users to read individual records or objects from a caGrid data service by working through a detailed scenario. This description applies only to caGrid data services that use CSM to manage instance-level security.

This page is organized into the following sections:

• Assumptions
  The assumptions about how things are before the start of the scenario.
• Authorization Policy
  A description of an authorization policy to be implemented.
• Policy Configuration
  A step-by-step description of how to configure CSM to enforce the policy.
• CQL to CQL
  A summary of differences between working with the CQL processor and the CQL preprocessor.

Assumptions

At the beginning of this scenario, we assume a caGrid data service is running that provides read-only access to the database of an application called OpenClinica. OpenClinica is a caCORE-based open-source clinical trial management application.

We assume that the data service has been configured to use the CSM-aware replacement CQL processor from the CQL_CSM library for instance-level security.

We assume that no CSM instance-level filters have been defined before the start of this scenario. The significance of this is that any user who is able to retrieve any data from the data service is able to retrieve all data from the data service. This is because when CSM has no instance-level filters associated with a class of data, then it places no constraints on which instances of that class a user can retrieve.

We assume that an instance of the CSM service is running that can be used to configure the CSM tables that govern CSM authorization for the OpenClinica data service.

We assume that the UI companion to the CSM service has been installed in the GAARDS UI.

Authorization Policy

The data service's domain model includes these two classes:

• org.cvrg.domain.Study
  An instance of study describe a clinical research study that involves many subjects.
• org.cvrg.domain.Subjects
  People who participate in one or more studies.

We want to configure a security policy to govern access to study and subject objects. If someone is an investigator for a study, they are authorized to see information describing the study and also information describing the subjects participating in the study. More specifically, investigators for a study are authorized to read the study object that describes the study. Investigators are also authorized to read subject objects that describe subjects that participate in the study.

Policy Configuration

Configuring CSM to support this policy involves a number of different types of data. These are:

• Instance-level configuration (in the table CSM_FILTER_CLAUSE)
• Protection Elements (in the table CSM_PROTECTION_ELEMENT)
• Protection Groups (in the table CSM_PROTECTION_GROUP)
• Roles (in the table CSM_ROLE)
• User Groups (in the tables CSM_GROUP, CSM_USER and CSM_USER_GROUP)
• Permissions (in the table CSM_USER_GROUP_ROLE_PG)

Instance-Level Configuration

The steps for instance-level configuration are described in the following paragraphs:

1. We launch the GAARDS UI. The details of how to do this are described on the Launching the CSM Administration Interface page.
   
   
2. We log onto the grid with with an identity that is authorized to administer the relevant instance of the CSM service. The details of how to do this are described on the Logging onto the Grid page.

   Getting Authorized to Administer CSM One or more users are authorized to administer the CSM service instance as part of the CSM service installation process. Additional users can be authorized to administer CSM through the GAARDS UI.

   
   
   

3. To access most CSM administration features, we must use the Manage Access Control window. We click on the Access Control menu item and choose the Manage Access Control item to launch the window.
   

   Select manage access control

   
   
4. The Manage Access Control window appears.
   

   application access control interface

   
   
   
5. On the top of the Manage Access Control window in the Service field, we select the instance of the CSM service we want to use to administer authorization policies. This is easy if the UI is configured to display the URL of only one CSM service. Otherwise, we need to know the correct CSM service to choose.

   Configuring the CSM Services List The list of CMS services that appears in the Manage Access Control window is manually configured during installation. If you want to work with a CSM service that is not on the list, you can edit the list of CSM services by modifying the CMS preferences for the GAARDS UI.

6. In the Credential field, we select the credential that we will use to do the administration. This should be the grid identity we just logged in with.

   The credential list always contains "Globus Default Proxy", which is a convenient default. However, if you are logged into the grid with more than one identity, "Globus Default Proxy" might not be the identity that you think it is. Selecting the actual identity rather than "Globus Default Proxy" can avoid mysterious problems later on.

   
   

7. We click on the Search button. A list of services and applications for which the CSM service manages authorizations appears in the lower half of the Manage Access Control window. It looks like this:
   
   
   The rows of the list have a background that alternates between white and light blue. This makes the list easer to read when there are many rows. When there are just a few rows, do not mistake the light blue for a selected row.
   
   
8. We select the OpenClinica application for which we will be managing authorizations. This is what the list looks like with a selected row:
   
   
   
   
9. We click the View button. After clicking on the View button, the Application Access Management window appears to administer CSM policies for the OpenClinica service. We click on its Instance Level tab. It looks like this.

   Blank Instance tab

10. The next step is to load the data service's domain model into the CSM service. This is necessary because the CSM service needs the openClinica service's data model to understand its instance-level security policies. The domain models are not stored in the database, so we need to load the data model from a file.
    
    When working with data from a caCORE application, there are two kinds of files we can get the domain model from. We can generate the domain model from the hibernate model that the caCORE SDK creates or we can get it from the domain model XML file. Which of these two options to use is determined by the data service for which we are configuring instance-level authorization.
    
    If the data service uses the replacement CQL processor (the recommended approach for data services that get data from a relational database), then the domain model must come from the hibernate model. How to do this is described in the following paragraphs. Getting the domain model from the domain model file is the what you must do for data services that use the CQL preprocessor. We describe this alternative in the last part of this page under the heading CQL to CQL.
    
    caCore-based data services have two .jar files that contain their hibernate model. These files have names that follow the pattern serviceName-beans.jar and serviceName-orm.jar. For the openclinica data service, the names of the files are openclinica-beans.jar and openclinica-orm.jar.
    
    To begin the process of loading the contents of these files, we click on the create via application jars button. The Configure the application dialog appears. It looks like this.

    
    

11. We use the browse buttons to fill in the Application Beans File field and the Application ORM File field with the paths of the two .jar files. We also delete the contents of the Hibernate Configuration field, which should be blank. When we are done, it looks like this:

    
    

12. We click on the verify button. A progress indicator appears while the UI reads the file and verifies the validity of its contents. When the verification finishes successfully, the progress indicator disappears and is replaced by the word “Verified” in the lower right corner of the dialog. The next button is now enabled. The dialog now looks like this:

    
    

13. Click on the next button. The Configure the application dialog disappears and a Create security filters dialog appears. It looks like this:

    
    

14. Before continuing, you should understand what CSM security filters are.
    
    We look at the list of classes that we can choose to associate with a filter.

    
    

15. We begin creating our first filter by selecting the class org.cvrg.domain.Study. This selection means that the new filter will be associated with the class org.cvrg.domain.Study. The Create security filters dialog now looks like this:

    
    

16. The Filter Chain field will contain the sequence of associations from the filter class to the target class. This is currently empty. The unlabeled drop-down list under the Filter Chain field allows us to select associations to add to the list. The format of the choices in this drop-down list is targetClassName - AssociationName.
    
    In addition to the associations defined in the domain model, CSM pretends that every class has an association named “self” that associates the class with itself. CSM requires that the filter chain has at least one association in it, so we select the “self” association.
    
    Clicking the add filter button adds the association selected in the drop-down list to the Filter Chain field. After we click on the add filter button, the dialog looks like this:

    
    
    If we make a mistake and add the wrong association, we can remove the last association we added by clicking on the remove last filter button.
    
    

17. Now that we have identified a target class, there is a list of target class attributes for us to select from. The org.cvrg.domain.Study class has an attribute with the name id that contains a number value that uniquely identifies the study. We will select id as the value of the Target Class Attribute field.

    We are done specifying a filter that requires users be explicitly authorized to read Study objects. We always leave the Target Class Alias and Target Class Attribute Alias fields blank.
    
    

18. We click on the create button. We are now ready to enter another filter.

    
    

19. The next filter we create will be associated with the Subject class. Its target class will be Study and the target attribute will be the Study class's id attribute. We begin by selecting the org.cvrg.domain.Subject class in the Class Name field.

    
    

20. In the domain model, the Subject and Study classes are not directly associated with each other. Instead, they are associated through a third class: StudySubject. We select the association from Subject to StudySubject and click on the add filter button.

    
    

21. We next select the association from StudySubject to Study and click on the add filter button again.

    
    

22. The target class is now Study. Since we used the Study class's id attribute to identify studies for the other filter, we will do the same for this filter.

    
    
    We click on the create button to create the second filter. Since we have created all the filters we need, we click on the done button. The Create security filters dialog disappears.
    
    

23. At this point the Access Control Management window does not reflect that new filters that we just added. To get it to update itself, click on the load button.

    
    

24. The filters are listed by their associated class. Selecting a filter shows its details.

The window shows CSM filters for the Study class and the Subject class. The preceding screen shot shows details of the filter associated with the study class.

You have now seen all of the steps that are involved in creating CSM filters for instance-level authorization policies. The next step is to create protection elements that specify authorized values for the attributes specified in the filters.

The following section explains in greater detail how filters work. Though a better understanding of filters will help you understand how to use them, you can safely skip reading the next section.

Filters for Relational Databases and the Replacement CQL Processor

In this section we discuss some details of how filters work. The details here are specifically related to filters created for caCORE SDK applications or other applications that describe their relational database schema through hibernate mappings in .jar files that are organized in a way compatible with caCORE SDK applications.

If the domain model used to create filters comes from a domain model file, then the administration tool has no information about a relational database and creates filters that are suitable for the CQL pre-processor, but not the replacement CQL processor. If the data model comes from .jar files, then the administration tool is aware of the database scheme involved and will generate two pieces of SQL for each filter.

These pieces of SQL are Boolean expressions that the replacement CQL processor will incorporate into the WHERE clause of any query that references the class that the filter is associated with. The two boolean expressions for each incorporated filter are “OR”ed together with each other and the result is “AND”ed with the other constraints in the where clause.

One of the SQL expressions generated for a filter determines if the user who issued a query is directly authorized to read specific study objects. The other SQL expression is to determine if the user who issued a query is a member of a group that is authorized to read specific study objects.

Since these SQL expressions are too big to fit in the preceding screen shot, here is what the SQL for the group part of the filter looks like:

study_id in
  (select table_name_csm_.study_id from study table_name_csm_
   where table_name_csm_.study_id in
      (SELECT Distinct pe.attribute_value 
       FROM CSM_PROTECTION_GROUP pg, CSM_PROTECTION_ELEMENT pe, CSM_PG_PE pgpe,
            CSM_USER_GROUP_ROLE_PG ugrpg, CSM_GROUP g, CSM_ROLE_PRIVILEGE rp,
            CSM_ROLE r, CSM_PRIVILEGE p
       WHERE ugrpg.role_id = r.role_id
         AND ugrpg.group_id = g.group_id
         AND ugrpg.protection_group_id
             = ANY (select pg1.protection_group_id
                    from csm_protection_group pg1
                    where pg1.protection_group_id = pg.protection_group_id
                       OR pg1.protection_group_id
                          = (select pg2.parent_protection_group_id
                             from csm_protection_group pg2
                             where pg2.protection_group_id
                                   = pg.protection_group_id))
         AND pg.protection_group_id = pgpe.protection_group_id
         AND pgpe.protection_element_id = pe.protection_element_id
         AND r.role_id = rp.role_id
         AND rp.privilege_id = p.privilege_id
         AND pe.object_id= 'org.cvrg.domain.Study'
         AND p.privilege_name='READ'
         AND g.group_name IN (:GROUP_NAMES )
         AND pe.application_id=:APPLICATION_ID))

When the replacement CQL processor inserts this in a where clause, it substitutes for ":GROUP_NAMES" a comma separated list of the names of groups that the user who issued the CQL query is known to be a member of. It substitutes for ":APPLICATION_ID" the identifier it uses internally for the application.

The SQL expression for the user part of the constraint is similar to the expression for the group. The difference between the two is at the end. Here is what the end of the user SQL expression looks like:

         and p.privilege_name='READ'
         and u.login_name=:USER_NAME
         and pe.application_id=:APPLICATION_ID))

CQL_CSM substitutes for ":USER_NAME" the identity of the user that issued the CQL query.

Multiple filters may be specified for one object. CQL_CSM “AND”s them together.

Both of types of generated SQL expressions begin with the identifier "study_id". CQL_CSM expects and requires that these SQL expressions begin with an identifier that consists of the class name followed by "_id". Before inserting one of these expressions into a where clause, CQL_CSM prepends the alias it is using for the table whose contents are being filtered.

The SQL determines what values are acceptable for the attribute they are filtering on based on which protection elements are directly or indirectly associated with a combination of the user that issued the CQL query and a role that has the READ privilege. From this set of protection elements, the SQL expression uses the protection elements whose object ID field matches the name of the class whose attribute is being used as the basis for a filter.

Protection Elements

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.

CQL to CQL

In the preceding sections of this page, we described the details of configuring instance-level authorizations for data services that use the replacement CQL parser, which works by translating CQL into SQL. In this section, we describe the configuration of instance-level authorizations for data services that use the CQL preprocessor that adds constraints to the CQL queries that enforce all relevant authorization constraints.

Configuration of instance-level authorizations for data services that use the CQL preprocessor is very similar to configuration for data services that use the replacement CQL processor. There are just two details that are different:

• When configuring for the CQL preprocessor, get the domain model from a domain model file rather than a hibernate model in .jar files.

• When configuring for the CQL preprocessor, no SQL is generated for filters.