Access Keys:
Skip to content (Access Key - 0)

CSM

CQL Preprocessor Developer Guide

This portion of the developer guide describes the steps for implementing instance-level security for a data service by integrating it with the CQL_CSM library's CQL preprocessor.

Contents

Test Environment

The CQL preprocessor was tested in an environment that consisted of the following components:

Though untested, it is expected that the CQL preprocessor will work with newer versions of all these components.

Integrating with xService-Based Data Services

Current versions of xService (1.3.5 or later) can be integrated with the CQL pre-processor without writing any code. In other circumstances, some custom code is needed.

To integrate the CQL pre-processor with a data service based on xService, you just need to add a service property named cqlQueryProcessorConfig_CQLPreprocessor_Classname. If this service property has a non-blank value, xService assumes that the value of the property is the name of a class that it should use as a CQL pre-processor.

There are two recommended values for for the cqlQueryProcessorConfig_CQLPreprocessor_Classname service property.

  • The value edu.emory.cci.cqlCsm.cqlCsmCql.CqlNullPreprocessor will cause xService to call a pre-processor that just returns the query without any modification. This is a good choice when no instance-level security is needed.
  • The value edu.emory.cci.cqlCsm.cqlCsmCql.CqlCsmPreprocessor will cause xService to call the pre-processor that adds constraints based on CSM policies.

If you are integrating the CQL preprocessor with an xService-based grid service, then you can skip the next section of this page.

Custom Integration with a Data Service

Writing custom code to integrate the CQL preprocessor with a relatively simple. It involves passing a CQL query to the preprocessor and then passing the CQL query returned by the preprocessor to the existing CQL processor.

The CQL preprocessor should be called through the interface
edu.emory.cci.cqlCsm.cqlCsmCql.CqlPreprocessor
Here is the definition of the interface:

package edu.emory.cci.cqlCsm.cqlCsmCql;

import gov.nih.nci.cagrid.cqlquery.CQLQuery;

public interface CqlPreprocessor {
    /**
     * Pre-process/re-write/transform the given CQL query and return
     * the transformed CQL query.
     *
     * @param query The query to be pre-processed/re-written/transformed.
     * @param user The identity of the user this is for.
     * @return The pre-processed/re-written/transformed CQL query.
     */
    publicCQLQuery preprocess(CQLQuery query,Stringuser); 
}

You pass a CQL query to the preprocess method and the user that the query should be authorized for and it returns a possibly modified version of the original query.
Usually you will want the user to the the same user whose credentials were submitted with the CQL query. Here is some sample code to get the user:

import org.globus.wsrf.security.SecurityManager;
  ...
  StringuserId = SecurityManager.getManager().getCaller();

Two classes are provided that implement the CqlPreprocessor interface:

  • edu.emory.cci.cqlCsm.cqlCsmCql.CqlCsmPreprocessor
    This class is the preprocessor that will modify its given query to reflect authorization constraints.
  • edu.emory.cci.cqlCsm.cqlCsmCql.CqlNullPreprocessor
    This is a do-nothing implementation of the CqlPreprocessor interface. Its preprocess method just returns the same query that is passed to it.

Both of these classes have a zero argument constructor that you can used to construct instances of them.

Including the Preprocessor in Builds of a Data Service

In all cases, the data service will need access to the .jar that contains the pre-processor. The name of the .jar file is cql_csm-1.3.1.jar.

There are two reasonable way to make this .jar file available to a data service. One way is to download the source, build the .jar file and then add the .jar file to the repository directory in the data service's build tree.

However, to avoid having to add the .jar file to the data service's source repository, the recommended way to include the .jar file in the data service's build is to add an ivy dependency that will copy it from CCI's repository.

Add this to the dependencies in the project's ivy.xml file:

<dependency org="edu.emory.cci" name="cql_csm" rev="1.3.1" />

Under the top-level directory of your tree, in the antfiles/ivy/ivysettings.xml file, as the last element in

<ivysettings>
  ...
  <resolvers>
    <chain>
      ...
    </chain>
  </resolvers>
</ivysettings>

add this

  <url name="cci-resolver" m2compatible="true">
    <artifact pattern="http://repo.cci.emory.edu:8081/artifactory/libs-releases-local/[organization]/[module]/[revision]/[artifact]-[revision].[ext]" />
    <artifact pattern="http://repo.cci.emory.edu:8081/artifactory/libs-releases-local/[organization]/[module]/[revision]/[artifact].[ext]" />
  </url>

The result should look like this:

<ivysettings>
  ...
  <resolvers>
    <chain>
      ...
      <url name="cci-resolver" m2compatible="true">
        <artifact pattern="http://repo.cci.emory.edu:8081/artifactory/libs-releases-local/[organization]/[module]/[revision]/[artifact]-[revision].[ext]" />
        <artifact pattern="http://repo.cci.emory.edu:8081/artifactory/libs-releases-local/[organization]/[module]/[revision]/[artifact].[ext]" />
      </url>
    </chain>
  </resolvers>
</ivysettings>

Now that you have the new dependency configured in ivy, do a clean build of the grid service's entire project so that it is rebuilt with the new dependency.

Including the PostgreSQL JDBC Driver in Builds of a Data Service

The CSM tables used by the CQL preprocessor are kept in a PostgreSQL database. To communicate with the PostgreSQL database the preprocessor needs the PostgreSQL JDBC driver jar.

If you already have a PostgreSQL JDBC driver .jar file in the build of your data service, you can skip to the next section of this document. The rest of this section explains how to configure ivy to automatically download an appropriate .jar file and add it to the build of your data service.

To tell ivy that your data service will need a PostgreSQL JDBC driver .jar file, add this to the dependencies in you data service's ivy.xml file:

<dependency org="postgresql" name="postgresql" rev="8.3-603.jdbc3" />

If you already have ivy configured to look for .jar files in a repository that contains the needed .jar file, then you are done with the step. If you are not sure about this, try making a clean build of you data service to see if ivy is able to find the postgresql .jar. If it cannot find the .jar file, then you will need to configure ivy to look in a repository that contains the .jar file.

In the previous step, you added a url element to the ivysettings.xml file. Add the following directly after the url element that you added:

<url name="ibiblio" m2compatible="true">
  <artifact pattern="http://mirrors.ibiblio.org/pub/mirrors/maven2/[organization]/[module]/[revision]/[artifact]-[revision].[ext]" />
  <artifact pattern="http://mirrors.ibiblio.org/pub/mirrors/maven2/[organization]/[module]/[revision]/[artifact].[ext]" />
</url>

The Domain Model File

In order for the CQL preprocessor to work properly, your data service must have a domain model file. However, not all data services are created with a domain model file. Check to see if this file is present. It should be in the data service's project tree with a name like etc/ServiceName?domainmodel.xml, where ServiceName is the name of the grid service. For example, if the name of a service is ImageDataService, then the name of its domain model file would be etc/ImageDataService?domainmodel.xml.

If your grid service has a domain model file, you can skip the rest of this section and go to the next topic. Otherwise, you will need to use the following directions to create the domain model file.

  1. cd to $CAGRID_LOCATION/projects/dataExtensions
  2. ant xmiToDomainModel
  3. Point to the XMI file exported from EA or ArgoUML per the caCORE SDK 4.1 programmer's guide instructions.
  4. Select "caCORE SDK 4.x XMI from EA" or "caCORE SDK 4.x XMI from ArgoUML" as appropriate for the XMI type.
  5. Type in a project short name.
  6. Type in a project version.
  7. Click OK.
  8. Choose where to save your domain model file and type in a name.
If xmiToDomainModel Fails
If the command
ant xmiToDomainModel
fails, a likely cause is that the .xmi file you are using was not created in a way consistent with the instructions in chapter 10 of the caCORE SDK 4.1 Programmer's Guide. Try recreating the .xmi file, following the instructions in that chapter.

Creating the CSM Database

The CQL pre-processor uses a PostgreSQL database to store CSM authorization policies. You need to create this database, unless it already exists. The CQL_CSM library provides an ant script to create the database.

There are a few things you must do to prepare before running the ant script:

  • You will need to make sure that PosegreSQL is installed. The ant script was tested with PostgreSQL 8.1, but more recent versions should work.
  • You will need to create some user IDs (described below).
  • You will need to download and prepare the CQL_CSM library (described below).
  • You will need to modify the script with the name of the database to be created (described below).

The ant script assumes these three user IDs are defined in the PostgreSQL instance:

  • One user must be have the ID csm. This user must be created with CREATEDB. The csm user is the user will own the CSM tables. The csm user ID will not be used for any runtime or production purposes.
  • One user must have the ID csm_adm. This user ID will be granted permissions needed to modify the contents of the CSM tables. The CSM service should be configured to use the csm_adm ID for connecting to the database.
  • The other user must have the ID csm_app. This user ID will be granted read-only access to the CSM tables. Your data service should use the csm_app ID for connecting to the database.

Download the CQL_CSM Configuration Scripts, if you have not already done so. Unpack the .zip file into the root directory of the for the caGrid service you are integrating with. This will be a directory that contains a build.xml file. For the convenience of these instructions, we will refer to this directory as SERVICE_HOME.

To ensure that all artifacts needed by the ant script and the preprocessor are present, issue these commands:
 cd SERVICE_HOME
 ant all

In the SERVICE_HOME directory is a file named dev-build.xml. This file contains a comment that looks like:

<!-- ============================================================== -->
<!-- Place any other properties you will need here                  -->
<!-- ============================================================== -->

Under this comment, add these lines:

<property name="csm.postgresql.csm.dbname" value="dbname"/>
<import file="CSM_pg/db_build.xml" />

where dbname is the name of the database the data service will be using. For example, if the name of the database is snpdb, then change the line to look like

<property name="csm.postgresql.csm.dbname" value="snpdb"/>

To create the CSM database issue these commands:
cd SERVICE_HOME
ant createPostgresqlCsmDatabase

The first time that you issue this command, it will prompt you for some information about your database. It collects this information in the file SERVICE_HOME/CSM_pg/csm.properties. Subsequent times that you issue this command it will not prompt you for this information. Instead, it will read the stored information from the file. If you want to enter different information, then edit or delete the file.

Deploying csm.properties

When you have finished creating the CSM tables, you will also have created the file SERVICE_HOME/CSM_pg/csm.properties. You need to copy this csm.properties file to the etc directory in your data service's build directory structure.

Issue a command like
cp SERVICE_HOME/CSM_pg/csm.properties SERVICE_HOME/etc

After you have copied the csm.properties file to the etc directory, you can (re)deploy your service into its container and the csm.properties file will be in a place where the service will be able to find it.

Install the CSM Service and GAARDS Client

Install the version 1.3.1 of the CSM service on the same host as your data service. You will use this to administer instance level security and any other sorts of CSM security policies that you may be using. You can download the CSM service from the Inventrio downloads page.

The csm.properties file you created in the previous step can be used to configure the CSM service. When you get to the place in the CSM service installation instructions where it tells you to edit a file named csm.properties you should first copy SERVICE_HOME/CSM_pg/csm.properties over that file.

The installation instructions for the CSM service describe a step titled, "Step 6: Initialize CSM database or tables (optional)". You should skip this step, as you have already created the database.
Last edited by
Mark Grand (556 days ago)
Adaptavist Theme Builder Powered by Atlassian Confluence