h2. Integrating CSM Authorization Policy into a caGrid Service Using the Authz Component
----
The *Authz* component of caGrid provides integration of the [NCICB's Common Security Module (CSM)|http://ncicb.nci.nih.gov/infrastructure/cacore_overview/csm] with caGrid services. This document demonstrates how to use Authz by providing a simple tutorial.

In this tutorial we will
# Create a simple service using Introduce
# Secure our service using Transport Level Security (TLS)
# Enforce authorization policy using both of the approaches supported by caGrid
# See how to extend the declarative authorization framework.

You will need
* Java 1.5
* Ant 1.6.5 (or higher)
* Eclipse 3.2\+
* Jakarta Tomcat 5.0.28 (or higher)
* Globus Toolkit 4.0.3
* caGrid 1.0 source distribution
* Access to a CSM database and UPT with administrative privileges
* Trust fabric synchronization with some grid (preferably the NCICB grid)
* Grid credentials
* Access to a GridGrouper service and privileges to create stems and groups and assign users

Please note that this is a work in progress. Your comments/suggestions are welcomed.


h3. Creating a Secure Service Using Introduce

Let's start by creating a simple service that concatenates strings.

In CAGRID_HOME/projects/introduce, type:

{code}
ant introduce
{code}

The Introduce GUI will appear. Enter the basic service information as shown:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure1|attachmentname=Howto_authz_figure1.png|caption=Figure 1: Enter Basic Service Information}
The press the _Create_ button. When Introduce is finished, you'll see a screen like this:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure2|attachmentname=Howto_authz_figure2.png|caption=Figure 2: An Introduce-created Service}
Our service should have an operation that takes two strings and concatenates them. Navigate to the _Operations_ tab and select the _Add_ button. This will open an editor in which you can specify inputs, outputs, faults, etc.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure3|attachmentname=Howto_authz_figure3.png|caption=Figure 3: Adding Operations}
Create two input parameters, _s1_ and _s2_, each of type _string_ (that's XML Schema string). Create an output parameters, also of type _string_. Then click _Done_.

Now we want to secure the service.

{info}
*NOTE:* Some kind of authentication method is required to support authorization (which is the main subject of this tutorial). Globus supports three method, which are all based on the use of X.509 certificates: Transport Layer Security (TLS), Secure Conversation, and Secure Message.
{info}

We will use Introduce to configure the service to require that clients use TLS with a privacy protection level.

Click the _Security_ tab. Select the _Custom_ radio button. Check the _Transport Level Security_ check box. Select _Privacy_ as the _Communication Method_.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure4|attachmentname=Howto_authz_figure4.png|caption=Figure 4: Specifying TLS Communication}

And then click Save.

At this point, Introduce has created an Eclipse project under the directory that you specified. We want to go right ahead implement the _concat_ operation, so we'll open this project in Eclipse.

To open the project in Eclipse, right-click in the Package Explorer view and select the _Import..._ option from the context menu. Then select _General > Existing Projects Into Workspace_ option, and click _Next_.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure5|attachmentname=Howto_authz_figure5.png|caption=Figure 5: Importing the Project Into Eclipse}

Then you'll have the option to navigate to the root directory of the project to be imported. Navigate to the directory that you specified in Introduce.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure6|attachmentname=Howto_authz_figure6.png|caption=Figure 6: Select Your Introduce Project}

Click the _Finish_ button.

After you've imported the project and expanded some of the nodes, your package explorer view will look like this:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure7|attachmentname=Howto_authz_figure7.png|caption=Figure 7: Project Hierarchy}

We'll first add some code to ConcatServiceImpl.java, and then add some code to ConcatServiceClient.java so that we can test the service.

Open ConcatServiceImpl.java and implement the concat operation like this:

{code}
public String concat(String s1, String s2) throws RemoteException {
return s1 + s2;
}
{code}

Then, in ConcatServiceClient.java, change the main method to look like this:

{code}
import org.globus.gst.GlobusCredential;
...
public static void main(String[] args) {
System.out.println("Running the Grid Service Client");
try {
String url = args[0];
String proxyFileName = args[1];
GlobusCredential cred = new GlobusCredential(proxyFileName);
ConcatServiceClient client = new ConcatServiceClient(url, cred);
System.out.println(client.concat("Howdy ", "Pardner!"));
} catch (Exception e) {
e.printStackTrace();
System.exit(1);
}
}
{code}

Now we are ready to deploy the service. Make sure to set your CATALINA_HOME environment variable to the Tomcat root directory. Then, in your new project root directory, type:

{code}
ant deployTomcat
{code}

This will deploy your service to Tomcat. Once that's done, you can start up Tomcat.

{code}
cd $CATALINA_HOME
./bin/startup.sh
{code}

You can check that everything started up correctly by pointing your browser to this URL:

{code}
[http://localhost:8080/wsrf/services]
{code}

You should see a list of the deployed service. Check that there is one named *cagrid/ConcatService*. If you don't see anything, check CATALINA_HOME/logs/catalina.out for something like this:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure8|attachmentname=Howto_authz_figure8.png|caption=Figure 8: Error Caused by Missing Credentials}

This means your container credentials are not in the right place. Make sure they are where you specified in CATALINA_HOME/conf/server.xml.

Before we can test out the service, we need to acquire some credentials so that the service can verify our identity. The GAARDS project provides a GUI to interact with the Dorian, the service that is responsible for issue grid credentials to users of caGrid. This GUI also allows you to specify the Identity Provider (IdP) that will provide an assertion to Dorian that you are who you claim to be.

In CAGRID_HOME/projects/security-ui, type:

{code}
ant ui
{code}

The GAARDS GUI will come up. Press the *Login* button and select the appropriate *Identity Provider*. The following image shows how this interface looks when the user wants to authenticate with the *cagrid-auth IdP* identity provided, which allows NIH users to obtain grid credentials using the NIH credentials.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure9|attachmentname=Howto_authz_figure9.png|caption=Figure 9: Login to NCICB's Grid}

Enter your username and password. Then press the *Authenticate* button.

The following window will appear.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure10|attachmentname=Howto_authz_figure10.png|caption=Figure 10: Saving the User Proxy}

Click the *Save Proxy* button and save the proxy file to your service's project directory. Now we are ready to run the grid service. Let's run the client with Ant. In your project directory edit the *run-tools.xml* file. As follows:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure11|attachmentname=Howto_authz_figure11.png|caption=Figure 11: Running Client with Ant}

You should see this in CATALINA_HOME/logs/catalina.out:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure12|attachmentname=Howto_authz_figure12.png|caption=Figure 12: catalina.out}

And you should see this in your console window:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure13|attachmentname=Howto_authz_figure13.png|caption=Figure 13: Console Output}

If you get some error about "Unknown CA", then you do not have the certificate of the CA that signed the conainer's certificate in your $HOME/.globus/certificates directory.

At this point, we've verified that authentication is working. Again, without authentication, we do not have the identity of the caller, which we need to do authorization.


h3. Adding CSM Authorization Using Introduce

Now we are ready to add CSM authorization to this service. There are two ways to do this in caGrid. The first approach is API-based. One can use Introduce to specify that access the service or operations in the service should be authorized against CSM authorization policy. Introduce will generate the necessary code in your grid service. The second approach uses the declarative security configuration framework that is provided by the Globus Toolkit.

We'll use the use the API-based approach first, and then use the declarative approach afterward.

Let's start by restricting access to the service. To do express this in CSM terminology, we need to create a *protection element* to represent the service. And specify that the user must have a certain *privilege* on that protection element. We also need to tell CSM what policy or *application context* applies to this protection element.

We'll use the following:
* Application Context: *demo1*
* Protection Element: [http://authz.tutorials.cagrid.org/ConcatService]
* Privilege: *ACCESS*

{info}
*Note:* The projection element can be any string. But I like to use the XML namespace of the service's WSDL.
{info}

Now, caGrid authorization is based on membership in groups that have been defined in GridGrouper some grid grouper service. So, we need to create a group in CSM that has the ACCESS privilege on the protection element that represents our service.

We'll use this group name:
{noformat}
[https://localhost:8543/wsrf/services/cagrid/GridGrouper}st1:grp1]
{noformat}

The structure of this group name is interpreted by the caGrid authorization component to mean that it should verify with the GridGrouper service (running at [https://localhost:8543/wsrf/services/cagrid/GridGrouper|https://localhost:8543/wsrf/services/cagrid/GridGrouper]) whether the user is a member of the *st1:grp1* group. If so, it will grant the user whatever privileges that group has been provisioned with in CSM.

Now we'll walk through the process adding authorization to our grid service, constructing the authorization policy in CSM, mapping it to a group in GridGrouper, and adding the user to the correct GridGrouper group.

In Introduce, click on the *Security* tab, and then the *Authorization* sub tab. This is where you set up authorization at the service level. Select *Common Security Module (CSM)* from the *Authorization Mechanism* drop-down list.

Enter the follow items:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure14|attachmentname=Howto_authz_figure14.png|caption=Figure 14: Configuring Authorization at the Service Level}

To see the difference between service-level and operation-level, let's create another operation named *concat2*, with the same signature and return type as the *concat* operation. Then, click the *SecurityTransport Level Security* tab for that operation. with a *privacy* protection level should already be selected. Select the *Authorization* sub tab. Select *Common Security Module (CSM)* from the *Authorization Mechanism* drop-down list. Then enter the following items:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure15|attachmentname=Howto_authz_figure15.png|caption=Figure 15: Specifying Operation-level Authorization}

This means that the user must have the EXECUTE privilege on this protection element:

{noformat}
[http://authz.tutorials.cagrid.org/ConcatService}concat2]
{noformat}

...which is the QName of the operation in the service's WSDL. Again, this is strictly a convention. Notice too, that we are using the same application context.

Press the *Done* button, and then the *Save* button. Introduce will update your service, adding the appropriate code. Let's take a look at this code. The two classes that are modified are highlighted in the following image:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure16|attachmentname=Howto_authz_figure16.png|caption=Figure 16: Introduce-generated Authorization Code}

In ConcatServiceProviderImpl.java, calls to ConcatServiceAuthorization.java before invoking the service implementation.

{code}
public class ConcatServiceProviderImpl{
...
public Concat2Response concat2(Concat2Request params) throws RemoteException {

ConcatServiceAuthorization.authorizeConcat2();
Concat2Response boxedResult = new Concat2Response();
boxedResult.setResponse(impl.concat2(params.getS1(),params.getS2()));
return boxedResult;
}

public ConcatResponse concat(ConcatRequest params) throws RemoteException {

ConcatServiceAuthorization.authorizeConcat();
ConcatResponse boxedResult = new ConcatResponse();
boxedResult.setResponse(impl.concat(params.getS1(),params.getS2()));
return boxedResult;
}
}
{code}

And it ConcatServiceAuthorization.java, calls are made directly to CSMGridAuthorizationManager to verify authorization on the configured protection elements.

Notice that we did not specify authorization for the *{_}concat{_}* method. So, the service-level authorization is used to protect that operation. On the other hand, we *did* specify authorization on the *concat2* operation, so the operation-level authorization is checked there.

Introduce generates all the necessary code, but you still have to do a couple of things by hand. First, you need to specify the CSM ApplicationSecurityConfig.xml file to be used. In your project directory, edit the service.properties file, and set the value of the *csmConfiguration* property to the absolute path to you CSM configuration file. (see the appendix for an example of this file and the associated Hibernate configuration).

Second, you need to make sure the CLM ObjectStateLoggerConfig.xml file ends up on your service's classpath in Tomcat (i.e. in WEB-INF/classes). The easiest way to do that is to put that file into the source directory of your project. It will be deployed correctly.

Now we need to set up the authorization policy in our CSM database. A logical representation of the set of associations that we want to create is shown in the following image.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure17|attachmentname=Howto_authz_figure17.png|caption=Figure 17: Logical View of CSM Authorization Policy}

First we will create the protection elements. Note that a protection element has a name and an *object ID*. It is the object ID that matters. Use some meaningful abbreviation for the name.

Log into your UPT, by entering the admin username, password, and the name of the application context. For this tutorial, the application context is *demo1*.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure18|attachmentname=Howto_authz_figure18.png|caption=Figure 18: Logging into UPT}

From the initial UPT page, click the *PROTECTION ELEMENT* tab. Click the *Create A New Protection Element* link. Enter a protection element name and object ID. Then click the *Add* button. The two images below show the creation of these two protection elements.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure19|attachmentname=Howto_authz_figure19.png|caption=Figure 19: Creating the Service Protection Element}

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure20|attachmentname=Howto_authz_figure20.png|caption=Figure 20: Creating the Operation Protection Element}

Now let's create the protection group. Click on the *PROTECTION GROUP* tab and click the C{*}reate A New Protection Group* link. Enter the protection group name as shown below.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure21|attachmentname=Howto_authz_figure21.png|caption=Figure 21: Creating a Protection Group}

Press the *Add* button. Then press the *Associated PEs* button. Select our two protection elements from the top list and press the *{_}Assign{_}* button. Then press the *Update Association* button.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure22|attachmentname=Howto_authz_figure22.png|caption=Figure 22: Assigning Protection Elements to a Protection Group}

Now let's create the role. Click the *ROLE* tab and click the *Create A New Role* link. Enter the name of the role as show below.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure23|attachmentname=Howto_authz_figure23.png|caption=Figure 23: Creating a Role}

Click the *Add* button. Then click the *Associated Privileges* button. Select the *ACCESS* and *EXECUTE* privileges from the top list and click the Assign button. Then click the *Update Association* button.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure24|attachmentname=Howto_authz_figure24.png|caption=Figure 24: Adding Privileges to a Role}

Finally, let's create the group and add the protection group and role to it.

Click the *GROUP* tab. Select the *Create A New Group* link. Enter the group name as shown below.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure25|attachmentname=Howto_authz_figure25.png|caption=Figure 25: Creating a Group}

Click the *Add* button. Then click the *Assign PG & Roles* button. Select *ConcatService* from the *Available Protection Groups* list and press the *Assign* button. Then select the *ConcatService.INVOKERS* role from the *Available Role{*}s list and press the *Assign* button.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure26|attachmentname=Howto_authz_figure26.png|caption=Figure 26: Assigning a Protection Group to a Group}

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure27|attachmentname=Howto_authz_figure27.png|caption=Figure 27: Assigning a Role to a Group}

Press the *Update Association* button.

That's it. Now click the *Associated PE & Privileges* button. This will display the protection elements and privilege pairings that have been granted to this group.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure28|attachmentname=Howto_authz_figure28.png|caption=Figure 28: PEs and Privileges Granted to a Group}

{info}
*NOTE:* that we have granted both *ACCESS* and *EXECUTE* on both protection elements. That will work for this example, but it more access than absolutely required. To achieve finer-grained policy control, one can create roles that contain a single privilege and protection groups that contain a single protection element. But if we had done that, then I would've had to paste even more images into this already lengthy tutorial.
{info}

So, at this point, we have used Introduce to generate code that will enforce an authorization policy that is defined in our CSM. And we have defined that policy in CSM. Now all that is left to do is ensure that the caller of our grid service is a member of the appropriate group in GridGrouper.

Recall that the group name is \_{[https://localhost:8543/wsrf/services/cagrid/GridGrouper}st1:grp1|https://localhost:8543/wsrf/services/cagrid/GridGrouper%7Dst1:grp1]. *This means that in the GridGrouper service that is running at* [https://localhost:8543/wsrf/services/cagrid/GridGrouper|https://localhost:8543/wsrf/services/cagrid/GridGrouper], *there must be a stem named \_st1* and within that stem, there must be a group named *grp1*. And, our caller must be a member of that group.

Now we'll look at how to create this group and add the grid identity of the caller to it. You'll need the appropriate privileges in your GridGrouper to do the following (or ask your GridGrouper administrator to do it for you).

In CAGRID_HOME/projects/security-ui, type:

{code}
ant ui
{code}

The GAARDS GUI will load. Make sure to login as a user that has the appropriate privileges in GridGrouper. Once you've logged in, your credentials (grid proxy) will be available to use other tools in the GAARDS GUI.

Click on the *Group Management* button. Then click the *Add Grid Grouper* button and select you credentials in the pop-up window.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure29|attachmentname=Howto_authz_figure29.png|caption=Figure 29: Loading a Grid Grouper Instance}

Click the Add button. You will see the GridGrouper tree load in the left-hand panel. Select the root stem of the tree and click the View button. The properties of that stem will load in the right-hand panel. Select the Child Stems tab, and enter values st1 for Local Name and st1 for Local Display Name as in the following image.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure30|attachmentname=Howto_authz_figure30.png|caption=Figure 30: Adding the Stem}

Click the *Add Child Stem* button. The new step will appear in the list of child stems. Select that stem and click the *View Stem* button. Then click the *Groups* tab for that stem. Enter *grp1* in the *Local Name* field and *grp1* in the *Local Display Name* field. Press the *Add Group* button. You'll see the new group appear in the list of child groups.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure31|attachmentname=Howto_authz_figure31.png|caption=Figure 31: Adding a Group to the Stem}

Now we need to add the caller's identity to this group. Recall that we had to create a proxy to use to invoke our grid service. It is the grid identity of the user that Dorian created the proxy for that we need to add to our new GridGrouper group. When you login to Dorian through GAARDS, your proxy is displayed to you. Your grid identity is one of the properties that are displayed.

So, let's log into Dorian again to get our grid identity. Press the *Login* button. Enter your username and password (and make sure to select the right IdP). Press the *Authenicate* button. Then copy the value of the *Identity* field.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure32|attachmentname=Howto_authz_figure32.png|caption=Figure 32: Getting the Grid Identity}

In this case, my identity is

{code}
/OU=HOME/OU=LAPTOP/OU=Laptop User Group/OU=IdP [2]/CN=local_user
{code}

Now, go back to the GridGrouper interface. Select *grp1* from the list of child groups, and press *View Group* button. Then select the *Members* tab for that group. Click the *Add Member* button end enter the grid identity that we just obtained.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure33|attachmentname=Howto_authz_figure33.png|caption=Figure 33: Adding a Member to a Group}

Press the *Add Member* button. Click the *List Members* button to see the member you just added.

That's it\! We are ready to test this all out.

{info}
*NOTE:* If you've taken a little break (more than 12 hours) and come back to this. You'll have to re-save your proxy to file because the one you created before is now invalid.
{info}

Redeploy your grid service and restart Tomcat. Then run the client. If all goes well, you should see something in catalina.out like this:

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure34|attachmentname=Howto_authz_figure34.png|caption=Figure 34: Grouper Client Logging}

This means that when the GridGrouper client tried to contact the GridGrouper service, Globus attempted to use the *default* proxy. But, we haven't set up a default proxy. You can disregard this message. But it confirms that our service did call out to GridGrouper.

If all does not go well, and you see some sort of exception, keep in mind that the three most common problems are:
# Your CSM configuration file can't be found. Check that it is where you said it was.
# You didn't put ObjectStateLoggerConfig.xml on the classpath. Make sure it's either in your deployed jar (in our case ConcatService-common.jar) or in WEB-INF/classes.
# The group name that you created contains an incorrect GridGrouper service URL.

At this point, we've successfully created a grid service that uses transport level security and enforces a CSM authorization policy.


h3. Using the Declarative Authorization Framework

Now we will look at an alternative approach to enforcing authorization policy. Previously, we used Introduce to generate code into our service. That code made the necessary calls to the CSMGridAuthorizationManager to protect our service and operations. We refer to this as the *API-based* approach.

But caGrid also supports a declarative configuration approach that builds upon the pluggable authorization framework provided by the Globus Toolkit. This framework allows one to specify a chain of \_Policy Decision Points (PDPs)_that will be consulted before granted access to any of the service's operations. Globus provides several built-in PDPs, and custom PDPs can be plugged in. We have provided a custom PDP that will map elements of the SOAP body to protection elements and privileges in CSM so that a policy decision can be made.

The value of this approach is that it enables authorization policy to be enforced without modifying code, in cases where that is undesirable or impossible. For example, authorization can be enforced on any operation that has been deployed with the service, including operations that are implemented by operation providers (i.e. not implemented in your service itself). It also allows fine-grained authorization policy to be enforced. Since any element of the SOAP body can be mapped to a protection element and privilege, one can enforce object instance-level authorization.

Let's start by using Introduce to remove the authorization code that we had created. Bring up Introduce and press the *Modify Service* button. Then navigate to and select the *ConcatService* directory. Press the *Open* button.

Select the *Security* tab and then the *Authorizatio{*}{_}n_ sub tab. Select *No Authorization* from the *Authorization Mechanism* drop-down list. This will reset authorization on all the operations. So, we won't have to explicitly remove authorization on the *concat2* operation. Click the *Save* button.

Now if you look at ConcatServiceAuthorization.java, you'll see that the *authorizeConcat* and *authorizeConcat2* methods are empty.

Let's add a few more operations to our service so that we can examine the various features of *PDP-based* authorization approach.

Create a third operation, named *concat3* with the same signature and return type as the *concat* operation. Finally, let's create an operation that takes a complex data type.

Introduce allows you to load XML schemas from the file system. Any XML type that has been defined in such a schema is available as an input or output parameter for the operations that you define.

Create the following XML schema.

Then, in Introduce, select the _Types_ tab and the _File System_ sub tab. Click the _Browse_ button to navigate to and select this XML schema file. Click the _Add_ button. You'll see the namespace loaded into the _Data Types_ tree. Select the new namespace, and change the value of the _Package_ field to _org.cagrid.tutorials.authz.beans_ as shown below.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure35|attachmentname=Howto_authz_figure35.png|caption=Figure 35: Adding Data Types to Service}

Now select the _Operations_ tab and click the _Add_ button to add a new operation. Set the name of the operation to _concat4_, and create two input parameters, _s1_ and _s2_, of type [http://beans.authz.tutorials.cagrid.org/ConcatService}statement|http://beans.authz.tutorials.cagrid.org/ConcatService%7Dstatement]. Create an output parameter of type [http://beans.authz.tutorials.cagrid.org/ConcatService}compoundStatement|http://beans.authz.tutorials.cagrid.org/ConcatService%7DcompoundStatement].

Click the _Done_ button. Click the _Save_ button.

Make sure you've implemented _concat2_ and _concat3_. Then add the following implementation to _concat4_.

{code}
...
StatementType s3 = new StatementType();
s3.setId(BigInteger.valueOf(3));
s3.setValue("G'Day Mate\!");
CompoundStatement stmt = new CompoundStatement();
stmt.setStatement(new StatementType\[\]{s1, s2, s3});
return stmt;
...
{code}

This implementation just inserts the given statements into a new compoundStatement, and adds a new statement with an _id_ of 3.

Now let's use the PDP approach to enforce the authorization policy that we've already defined in CSM. Four steps are required to do this:
# Modify the service's security descriptor to specify that the caGrid PDP implementation should be used for authorization.
# Modify the services Axis deployment descriptor to point the PDP to its configuration file.
# Create a PDP configuration file.
# Configure CSM to use the CSMGridAuthorizationManager.
# Set the gov.nih.nci.security.configFile system property to point to our CSM configuration file.

Our service's security descriptor is located in our project directory at etc/ConcatService-security-desc.xml. Modify the _authz_ element in that file to look like this:

{code}
...
<authz value="csmPDP:gov.nih.nci.cagrid.authorization.pdp.impl.PDPDelegator" />
...
{code}

Our service's Axis deployment descriptor is located in the root of our project directory. Add a parameter to the service configuration as follows:

{code}
<deployment ...>
...
<service name="SERVICE-INSTANCE-PREFIX/ConcatService"
provider="Handler" use="literal" style="document">
...
<parameter name="csmPDP-beansFile"
value="ETC-PATH/pdp-config.xml" />
...
</service>
...
</deployment>
{code}

Now we need to create the PDP configuration file. In the etc directory, create a file named pdp-config.xml and insert the following XML.

Let's examine the contents of this file piece-by-piece. First of all, this is a Spring beans file. The first bean definition sets up our PDP implementation, _CSMPDP_. This class implements the basic mapping algorithm.

The CSMPDP requires that its _authorizationManager_ property be populated with and implementation of the _GridAuthorizationManager_ interface. It also requires that its _selectorSelector_ property be populated with an implementation of the _PENodeSelectorSelector_ interface.

The GridAuthorizationManager interface looks like this.

{code}
package gov.nih.nci.cagrid.authorization;

public interface GridAuthorizationManager {
public boolean isAuthorized(String identity,
String objectId, String privilege);
}
{code}

Given an _identity_, _objectId_, and _privilege_, it will return a _boolean_ indicating the authorization decision. For the CSMGridAuthorizationManager implementation of this interface, the _objectId{_}parameter represents the object ID of a protection element defined in CSM. The CSMPDP will map elements of the SOAP message to protection element object IDs and privileges and ask the GridAuthorizationManager instance if the caller _isAuthorized_. If the caller is not authorized for any object ID, authorization fails, and Globus will return a fault indicated that the caller is not authorized to invoke the operation.

But CSMPDP doesn't actually map SOAP message elements to object IDs itself. It delegates that behavior to other the objects that we set up in the rest of this PDP configuration file.

Let's look at the objects that CSMPDP delegates to.

The other property of CSMPDP is _selectorSelector_, which must be of type _PENodeSelectorSelector_. A PENodeSelector implementation is responsible for returning an implementation of _PENodeSelector_, given a _org.apache.axis.MessageContext_. The PENodeSelectorSelector interface looks like this.

{code}
package gov.nih.nci.cagrid.authorization.pdp;

import org.apache.axis.MessageContext;

public interface PENodeSelectorSelector {
PENodeSelector select(MessageContext context);
}
{code}

A PENodeSelector is responsible for returning an array of _PENode_ objects and the name of the privilege that applies to these objects, given a _org.w3c.dom.Document_ object that is the contents of the SOAP body. The PENodeSelector interface looks like this.

{code}
package gov.nih.nci.cagrid.authorization.pdp;

import org.w3c.dom.Document;

public interface PENodeSelector {
String getPrivilege();
PENode\[\] selectPENodes(Document doc);
}
{code}

A PENode object represents a mapping of a _org.w3c.dom.Node_ object, which is an element of the SOAP body, to the object ID of protection element. The PENode interface looks like this.

{code}
package gov.nih.nci.cagrid.authorization.pdp;

import org.w3c.dom.Node;

public interface PENode {
Node getNode();
String getObjectId();
}
{code}

The PDP configuration file builds and populates the instances of PENodeSelectorSelector and PENodeSelector that CSMPDP will use to do its job.

Let's return to the PDP configuration. The second bean definition, with an _id_ of _selectorSelector_, sets an implementation of PENodeSelectorSelector that will choose PENodeSelectors based on the QName of the operation being invoked.

In this case, our configuration file indicates that if the operation QName ends in _concat2_, then the PENodeSelector object with the bean ID of _concat2_ should be returned. Otherwise, a PENodeSelector object with the bean ID of _theService_ should be returned.

The value of the _pattern_ property on these RegExPENodeSelectorMapping objects must be a Perl5 regular expression. The patterns are evaluated against the operation QName in the order they are declared in this file. So, the most specific pattern should be placed first, while the most general pattern should be placed last. In this way, we can easily enforce service\- and operation-level authorization. If the operation does not match one of the more specific patterns, then if falls through to the most general pattern, which enforces service-level authorization.

Also note that if no PENodeSelector is returned, authorization fails. So, the default behavior is to deny access to the service.

Let's look at the two PENodeSelector objects now.

{code:xml}

Both of these PENodeSelector objects are of type ConstantPENodeSelector, which simply returns a single PENode object (actually and array of size 1) that has the _privilege_ and _objectId_ that are specified in this file.

These two beans enforce the same authorization policy that we had previously enforced using Introduce (i.e. by generated code into our service implementation).

Now we will modify the ApplicationSecurityConfig.xml file to indicate that the CSMGridAuthorizationManager class should be used instead of the default CSM implementation. Recall the when we did this with Introduce, the generated code instantiated CSMGridAuthorizationManager directly by calling the constructor. Here we want to use the Factory method provided by CSM's SecurityServiceProvider.

Modify the _demo1_ application context of your ApplicationSecurityConfig.xml file to look like this:

{code:xml}

The last thing we need to do is set the _gov.nih.nci.security.configFile{_}system property to point to our ApplicationSecurityConfig.xml file. We can do this by add this property to CATALIAN_HOME/conf/catalina.properties. The property should look like this:

{code}
gov.nih.nci.security.configFile=/Users/joshua/tutorials/authz/jakarta-tomcat-5.0.28/conf/demo1/ApplicationSecurityConfig.xml
{code}

Let's re-deploy the service and run the client. You should see the same results.

If you see some exception message like "... Error setting property values; ... PropertyAccessExceptionsException...", make sure you've configured CSM to use CSMGridAuthorizationManager, and not the default implementation.

At this point, we are enforcing the same authorization that we did using Introduce.

Now let's look at how we can enforce instance-level authorization. Suppose our client invokes the _concat4_ operation, passing in the following XML.

{code:xml}

And suppose that we want to restrict operations on particular statement objects. We can create object instance-level authorization policy in CSM and update our PDP configuration to enforce it.

This is the logical structure that we want to create in CSM.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure36|attachmentname=Howto_authz_figure36.png|caption=Figure 36: Statement Authorization Policy}

Construct this policy using the UPT (I won't include the screen shots here).

Then add the following to _pdp-config.xml_.

This new PENodeSelect object will select _statement_ Nodes from the SOAP body contents. Each Node will be passed to and ObjectIdGenerator. In this case, the ObjectIdGenerator will apply an XSL transformation to the Node to generate an object ID, using the literal _org.cagrid.tutorials.authz.beans.Statement._ and the value of the _statement_ element's _id_ attribute.

Now let's change the client to invoke the _concat4_ operation. Change the implementation as follows.

{code}
..
public static void main(String [] args){
System.out.println("Running the Grid Service Client");
try{
String url = args[0];
String proxyFileName = args[1];
GlobusCredential cred = new GlobusCredential(proxyFileName);
ConcatServiceClient client = new ConcatServiceClient(url, cred);

String statementFile = "test/resources/compoundStatement.xml";
String clientConfigFile =
"src/org/cagrid/tutorials/authz/client/client-config.wsdd";
CompoundStatement in = getCompoundStatement(statementFile, clientConfigFile);
CompoundStatement out = client.concat4(in.getStatement(0), in.getStatement(1));
StringWriter w = new StringWriter();
Utils.serializeObject(out,
new QName("http://beans.authz.tutorials.cagrid.org/ConcatService",
"compoundStatement"), w);
System.out.println(w.getBuffer());

} catch (Exception e) {
e.printStackTrace();
System.exit(1);
}
}

private static CompoundStatement getCompoundStatement(String statementFile, String clientConfigFile) {
CompoundStatement stmt = null;
try{
InputStream config = new FileInputStream(clientConfigFile);
Reader reader = new FileReader(statementFile);
stmt = (CompoundStatement)Utils.deserializeObject(reader,
CompoundStatement.class, config);
}catch(Exception ex){
throw new RuntimeException("Error deserializing compound statement: " +
ex.getMessage(), ex);
}
return stmt;
}
...

{code}

Be sure to place _compoundStatement.xml_ in the _test/resources_ directory. This code will deserialize that file, pull out the two _statement_ elements, and pass then to the _concat4_ operation. Then it will serialize the result to a string and print it out.

Re-deploy the service. Restart Tomcat. Run the client again. You should see the following output.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure37|attachmentname=Howto_authz_figure37.png|caption=Figure 37: A Compound Statement}

Notice that we have been granted access to _concat_ statements 1 and 2. This is what we expected. But also notice that the service returned a third statement with an ID of 3. Our authorization policy has not granted the caller authorization to this object, but since our PDP is not checking the returned results, the object was returned to the caller.

In fact, neither Introduce authorization tooling nor the Globus authorization framework will supports filtering of results. Usually, this is something that the underlying application should handle. But, in cases where the application does not enforce authorization on returned results, we can enforce it in the grid service by either modifying the code or creating an Axis Handler that will inspect the SOAP response message.

In the caGrid Authz component, we provide an Axis Handler that can be used to filter SOAP messages using the same components that are used in the PDP implementation.

Let's look at how to use this Handler to prevent the caller from getting objects for which he is not authorized.

Edit the Axis deployment descriptor (service-config.xml) to include the following.

{code:xml}
<deployment ...>
<handler name="responseFilter"
type="java:gov.nih.nci.cagrid.authorization.filter.FilterDelegator">
<parameter name="beansFile"
value="ETC-PATH/response-filter-config.xml" />
</handler>
<service name="SERVICE-INSTANCE-PREFIX/ConcatService"
provider="Handler" use="literal" style="document">
...
<responseFlow>
<handler type="responseFilter" />
</responseFlow>
</service>
...
</deployment>

{code}

Then, create a file named _response-filter-config.xml_ in the _etc_ directory, and add the following content.

{code:xml}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
<bean id="responseFilter"
class="gov.nih.nci.cagrid.authorization.filter.CSMNodeFilter">
<property name="authorizationManager">
<bean class="gov.nih.nci.security.SecurityServiceProvider"
factory-method="getAuthorizationManager">
<constructor-arg value="demo1" />
</bean>
</property>
<property name="selectorSelector" ref="selectorSelector" />
<property name="nodeHandler">
<bean class="gov.nih.nci.cagrid.authorization.pdp.impl.NodeRemovalPENodeHandler" />
</property>
</bean>
<bean id="selectorSelector"
class="gov.nih.nci.cagrid.authorization.pdp.impl.OperationPENodeSelectorSelector">
<property name="mappings">
<list>
<bean class="gov.nih.nci.cagrid.authorization.pdp.impl.RegExPENodeSelectorMapping">
<property name="pattern" value=".*concat4"/>
<property name="selector" ref="concat4"/>
</bean>

</list>
</property>
</bean>
<bean id="concat4"
class="gov.nih.nci.cagrid.authorization.pdp.impl.XPathPENodeSelector">
<property name="privilege" value="ACCESS" />
<property name="xpathMap">
<map>
<entry>
<key>
<value>//*[local-name(.)='statement']</value>
</key>
<bean class="gov.nih.nci.cagrid.authorization.pdp.impl.id.XSLTObjectIdGenerator">
<property name="xsl">
<value>
<![CDATA[
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output omit-xml-declaration="yes" method="xml"/>
<xsl:template match="*[@id]">
org.cagrid.tutorials.authz.beans.Statement.<xsl:value-of select="@id"/>
</xsl:template>
</xsl:stylesheet>
]]>
</value>
</property>
</bean>
</entry>
</map>
</property>
</bean>
</beans>
{code}
Most of this file can be copied direction from our PDP configuration. The important difference to notice is in the first bean definition....
{code:xml}
...
<bean id="responseFilter"
class="gov.nih.nci.cagrid.authorization.filter.CSMNodeFilter">
<property name="authorizationManager">
<bean class="gov.nih.nci.security.SecurityServiceProvider"
factory-method="getAuthorizationManager">
<constructor-arg value="demo1" />
</bean>
</property>
<property name="selectorSelector" ref="selectorSelector" />
<property name="nodeHandler">
<bean class="gov.nih.nci.cagrid.authorization.pdp.impl.NodeRemovalPENodeHandler" />
</property>
</bean>
...

{code}

First, the _responseFilter_ bean is implemented by _CSMNodeFilter_. Second, the _nodeHandler_ property expects an implementation of the _PENodeHandler_ interface. That interface looks like this.

{code}
package gov.nih.nci.cagrid.authorization.pdp;

public interface PENodeHandler {
public void handleNode(PENode node);
}
{code}

CSMNodeFilter will pass each PENode that the caller is not authorized for to the PENodeHandler. The PENodeHandler implementation decides what should be done with the Node contained in the PENode. The NodeRemovalPENodeHandler will simply remove the given Node.

Let's test it out. Re-deploy the service. Re-start Tomcat. Run the client again. You should see the following output.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure38|attachmentname=Howto_authz_figure38.png|caption=Figure 38: Output Without Unauthorized Content}

At this point, we have enforced authorization policy ant the service, operation, and object instance levels.

Now, recall that the default behavior of the CSMPDP is to deny access to the service, unless at least one PENode is selected and the caller is authorized for all selected PENodes. Suppose that we would like to change this behavior and open up the service's other operations while still requiring the user to authenticate (say, for auditing purposes).

There is no parameter on the CSMPDP that will change its default behavior, but because the Authz PDP framework uses Spring to inject dependencies into CSMPDP, we can achieve this by simply providing a different implementation of GridAuthorizationManager.

Create the following class in your project.

{code}
package org.cagrid.tutorials.authz.service;

import gov.nih.nci.cagrid.authorization.GridAuthorizationManager;

public class PublicAccessAuthzMgr implements GridAuthorizationManager {

private String publicPEs;

private GridAuthorizationManager authorizationManager;

public String getPublicPEs() {
return publicPEs;
}

public void setPublicPEs(String publicPEs) {
this.publicPEs = publicPEs;
}

public boolean isAuthorized(String identity, String objectId,
String privilege) {
boolean isAuthorized = false;

if (objectId.matches(getPublicPEs())) {
System.out.println("Granting '" + identity + "' public access to '"
+ privilege + "' on '" + objectId + "'.");
isAuthorized = true;
} else {
GridAuthorizationManager mgr = getAuthorizationManager();
System.out.println("Delegating to '" + mgr.getClass().getName()
+ "' for '" + identity + "' access to '" + privilege
+ "' on '" + objectId + "'.");
isAuthorized = mgr.isAuthorized(identity, objectId, privilege);
}

return isAuthorized;
}

public GridAuthorizationManager getAuthorizationManager() {
return authorizationManager;
}

public void setAuthorizationManager(
GridAuthorizationManager authorizationManager) {
this.authorizationManager = authorizationManager;
}

}

{code}

This class requires two properties _authorizationManager_ and _publicPEs_. The _publicPEs_ property is a regular expression which will be evaluated against the _objectId_ that is passed into the _isAuthorized{_}method. If it matches, then authorization will be granted. Otherwise, this class will delegate to an instance of GridAuthorizationManager (the _authorizationManager_ property).

We can integrate this new authorization manager implementation into our PDP configuration (pdp-config.xml) as follows.

First, make the CSMPDP use our new implementation.

{code:xml}
<beans>
<bean id="csmPDP"
class="gov.nih.nci.cagrid.authorization.pdp.impl.CSMPDP">
<!--
<property name="authorizationManager">
<bean class="gov.nih.nci.security.SecurityServiceProvider"
factory-method="getAuthorizationManager">
<constructor-arg value="demo1" />
</bean>
</property>
-->
<property name="authorizationManager"
ref="publicAccessAuthzMgr"/>
<property name="selectorSelector" ref="selectorSelector" />
</bean>

<bean id="publicAccessAuthzMgr" class="org.cagrid.tutorials.authz.service.PublicAccessAuthzMgr">
<property name="publicPEs" value="anyOperation"/>
<property name="authorizationManager">
<bean class="gov.nih.nci.security.SecurityServiceProvider"
factory-method="getAuthorizationManager">
<constructor-arg value="demo1"/>
</bean>
</property>
</bean>
...

{code}

Second, make the _theService_ PENodeSelector return _anyOperation_ as the _objectId_.

{code:xml}
<bean id="theService"
class="gov.nih.nci.cagrid.authorization.pdp.impl.ConstantPENodeSelector">
<property name="privilege" value="ACCESS"/>
<!--
<property name="objectId"
value="http://authz.tutorials.cagrid.org/ConcatService" />
-->
<property name="objectId" value="anyOperation"/>
</bean>

{code}

{info}
*NOTE:* We could have left this PENode selector as it is, but the regular expression to match the service URI would have been ugly.
{info}

To test this out, we will change the client to call the _concat2_ and _concat3_ operations in succession and look at what our service prints to the console.

{code}
...
System.out.println(client.concat2("Howdy ", "Pardner\!"));
System.out.println(client.concat3("Howdy ", "Pardner\!"));
...
{code}

Now we need to... You guessed it: Re-deploy the service. Re-start Tomcat. Run the client.

In _catalina.out_ you should see (somewhere) this...

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure39|attachmentname=Howto_authz_figure39.png|caption=catalina.out}

...and then this...

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure40|attachmentname=Howto_authz_figure40.png|caption=catalina.out again}

In your console window, you should see this.

{image-with-caption:tablealign=center|pagename=cagrid:Authorize Figure41|attachmentname=Howto_authz_figure41.png|caption=Console Output}

Now you should know how to use both Introduce and the CSMPDP to enforce authorization policy at multiple levels, and how to extend the CSMPDP framework to suit your needs.