4. Service Developer's Guide

Up one level

PBAC 2 : Service Developer's Guide

PBAC can be used to protect all SOAP invocations on your web services.

Each service will have a PBAC policy for any operations which don't take a context (these are similar to static methods and constructors in Java). This is described in the Services section below.

SOAP requests may also take a resource identifier in the SOAP header to provide context for the operations. Operations which take a context work like normal non-static methods in Java. Each resource has a unique identifier and a unique resource type; there is one PBAC policy for each resource type. Creating and managing resources is described in the Resources section.

The Web administration section shows how to create a web-based adminstrator interface easily using JSP. This lets you deploy and undeploy policies, view the resources protected by each policy, and change the dynamic rules for assigning process roles.

The client

No special features should be required on the client except for WS-Security support. If the context ID is passed in the header instead of the body, the client will need to be able to create these headers (typically by supporting WS-Addressing).

The PEP

The PEP wraps the service and prevents unauthorised users from invoking any operations on resources to which they have not been granted access. The PEP is intended to be very light-weight, as most of the work is done in the PDP. Each web service platform requires its own implementation of the PEP.

The client's SOAP message is received by the service framework, which processes it with a series of inbound handlers before invoking the service itself (see the Deployment section in the overview).

The PEP passes the user's X.509 certificate, the resource ID and the SOAP operation name to the PDP (either a local PDP, or a PDP Invoker).

The PDP locks the resource and then checks that the user is authorised to perform the operation. If not, it unlocks the resource and throws an exception, stopping processing of the message. If the user is authorised, the check returns success with the resource still locked.

On successful completion of the check, the PEP invokes the service operation itself. The service operation may signal events to the PDP during its invocation; these events may change the process state of the resource, with the service policy deciding to which state the resource will transition on each event.

After the service operation has been invoked (whether successful or not), the PEP tells the PDP to unlock the resource.

Axis deployment

The PEP class is in the itinnov-grid-pbac-pep-VERSION.jar JAR file. To use PBAC, the service's server-config.wsdd file must list the PEP as the provider. For example:

<service name="DataService" provider="java:PBAC-PEP" use="literal" style="wrapped">
  <requestFlow>
   <handler type="SecurityInboundHandler"/>
  </requestFlow>
  <responseFlow>
   <handler type="IntegrityEnforcementHandler"/>
  </responseFlow>
  <parameter name="className" value="java.package.MyServiceInterface/>
  <parameter name="allowedMethods" value="*"/>
  <parameter name="scope" value="Application"/>
 </service>

Note: WSS4J does not provide a configuration setting to disable calling the vertifyTrust method, which checks that the signing certificate is in the service's keystore. Since PBAC roots of trust are per-resource rather than global, this check must be disabled. This can be done by setting SecurityInboundHandler to a subclass of WSDoAllReceiver which overrides this method to always return true.

Note 2: When using the PBAC-PEP provider, the service's className attribute must be set to a Java interface rather than to the implementing class. This removes the need to set allowedMethods to an actual list of operations (since only operations in the interface are exposed) and permits any web-based configuration interface access to the same singleton implementation object. The implementing class to use for the interface is specified in the implementationfactory.properties file:

java.package.MyServiceInterface = com.example.MyServiceImpl

.NET filters

The .NET filters are written in C# and make use of the WSE 2 libraries. Since the PDP requires a JVM it cannot be run in-process with .NET services, so the .NET filters communicate with the PDP using SOAP calls.

WSE 2 automatically includes the required WS-Security handlers, so this does not need to be listed. The service's Web.config file therefore only needs to list the PEP filter for both chains, eg:

  <microsoft.web.services2>

    <filters>
      <input>
        <add type="PBAC.PEPInputFilter, PBAC" />
      </input>

      <output>
        <add type="PBAC.PEPOutputFilter, PBAC" />
      </output>

    </filters>
    ...
  </microsoft.web.services2>
  

Services

To write a service that uses PBAC, you should already be familiar with creating web services using your chosen service container (eg, tomcat/axis or .NET).

Creating a service policy

The service policy controls access to operations that don't act on an existing resource. We'll start with a service which has just an echo operation. A suitable PBAC policy for our service might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<state-model description="My service"
 xmlns="http://www.itinnovation.soton.ac.uk/uk/ac/soton/itinnovation/grid/pbac2/staticpolicy/types">

	<state name="UNINITIALISED-STATE">
		<transition>
			<event name="init"/>
			<to-state name="active"/>
		</transition>
	</state>

	<state name="active">
		<operation name="echo">
			<process-role name="world"/>
		</operation>
	</state>

	<state name="DESTROYED-STATE"/>

</state-model>

All resources start in the UNINITIALISED-STATE state. Once initialisation is complete, the service will send the init event to change it to the active state. The service will stay in this state for the whole time it is deployed.

While in the active state, anyone with the world role may invoke the echo operation.

Registering the service with PBAC

When your service is configured, it should deploy the XML policy, and then create a singleton resource named service:java.package.MyServiceInterface (the same interface that was specified in the wsdd file):

PBACUtils.ensureDeployed(MyServiceInterface.MY_SERVICE_RESOURCE_TYPE, "my-service-policy.xml");
PBACUtils.ensureServiceResource(this, new MatchRule[] {MatchRule.createAnyoneRule("world"));

The first argument to ensureServiceResource is your service object, which must have a PEPServiceResource annotation on its class. Alternatively, you may pass the PBAC type and Java interface as arguments in place of this.

The second argument to creates an initial dynamic policy which gives anyone at all the world role. This is useful for completely public methods. The service policy above permits users with the world role to invoke the echo operation once the service is in the active state. Alternatively, you might choose to leave the initial policy empty and have the service administrator set it through the web interface.

MY_SERVICE_RESOURCE_TYPE is simply a unique string identifying the new type. To ensure that it is unique, it is usual to pick an unused URL in a domain that you control. Including the year that the URL was coined means you only have to remember which names you've already used this year. For example:

public static final String MY_SERVICE_RESOURCE_TYPE =
		"http://example.com/2006/MyServicePolicy";

Writing the echo opertion

The implementation of the echo operation doesn't require any interaction with PBAC. Add the prototype for echo to MyServiceInterface:

 public String echo(String message);

Add the implementation to MyServiceImpl:

public String echo(String message) {
	return "Echo: " + message;
}

Anyone should now be able to invoke the echo operation, since we granted everyone the world role.

Creating a web-based administration interface

Services generally export operations that can be used to manage the dynamic policy (e.g., who gets access to the world role). However, it is useful (especially during development) to have a web interface for this. This can be done with some simple JSP code:

<... resources of that type.</p><%

PolicyAdmin admin = new PolicyAdmin(request);
String message = admin.processPOST();
if (message != null)
  out.write("<p>" + message + "</p>");
admin.showAdmin(out);

The processPOST operation checks whether the user is submitting a form, and performs the requested action if so. It may return a message, which you should display to the user. The showAdmin operation displays the policy tables.

When you view this page you should see your new policy and, when you select it, you should see the singleton service object in the active state. Use of the administration interface is described in the PBAC administrator's guide.

Clicking on a resource takes you to the resource's page. You can configure which JSP page to link to for each resource type using registerResourceTypeLink. By default, the page pbac_resource.jsp is assumed, but customising this allows you to show extra resource-specific information:

admin.registerResourceTypeLink(MyServiceInterface.MY_SERVICE_RESOURCE_TYPE, "my_service.jsp");

To include the dynamic policy component in your web interface in the resource's page (my_service.jsp), use this code:

ACLadmin acladmin = new ACLadmin(request);
String message = acladmin.processPOST();
if (message != null)
	out.write("<p>" + message + "</p>");
acladmin.showRules(out);

This will produce the table shown below for our sample service (a groups section will also be shown if you have groups defined). Use of the dynamic policy administration interface is described in the PBAC administrator's guide.

Resources created by services

Some services only have operations with no context (like static methods on a Java class). Most services however will create other resources dynamically: an account service will create accounts, and a data service will create data stagers. Each such resource needs to have its own access control dynamic policy (every account will grant a different person the budget-holder process role, for example).

Creating a resource policy

For this tutorial, we'll extend our service to allow the creation of data stagers. Users will be able to create, write to, read from and destroy stagers. A simple initial policy might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<state-model description="DataService description"
	     xmlns="http://www.itinnovation.soton.ac.uk/uk/ac/soton/itinnovation/grid/pbac2/staticpolicy/types">

	<state name="UNINITIALISED-STATE">
		<transition>
			<event name="init"/>
			<to-state name="empty"/>
		</transition>
	</state>

	<state name="empty">
		<operation name="save">
			<process-role name="owner"/>
		</operation>
		<operation name="destroy">
			<process-role name="owner"/>
		</operation>

		<transition>
			<event name="write"/>
			<to-state name="full"/>
		</transition>
		<transition>
			<event name="destroy"/>
			<to-state name="DESTROYED-STATE"/>
		</transition>
	</state>

	<state name="full">
		<operation name="read">
			<process-role name="reader"/>
			<process-role name="owner"/>
		</operation>
		<operation name="deleteContents">
			<process-role name="owner"/>
		</operation>

		<transition>
			<event name="delete"/>
			<to-state name="empty"/>
		</transition>
	</state>

	<state name="DESTROYED-STATE"/>
</state-model>

Apart from the special uninitialised and destroyed states, a stager can be either empty or full. When empty, anyone with the owner role can write to it or destroy it. When full, the owner can delete the contents and both the owner and any reader can read the data.

This model introduces some constraints on how a stager is used. For example, no-one (not even the owner) can destroy a stager which is in the full state. It must be moved to the empty state first.

Add a line to your initialisation code to deploy the resource policy:

PBACUtils.ensureDeployed(MyServiceInterface.MY_SERVICE_RESOURCE_TYPE, "my-service-policy.xml");
PBACUtils.ensureDeployed(MyServiceInterface.MY_RESOURCE_TYPE, "my-policy.xml");
PBACUtils.ensureServiceResource(this, new MatchRule[] {MatchRule.createAnyoneRule("world"));

The web interface should now list both resource types, although there won't be any objects listed for the new type because no data stagers have been created yet.

Creating a new resource

New resources are registered with PBAC using newProcess. Typically, there is a web service operation which does not take a resource ID as input (and hence is protected by the PBAC service policy above, rather than by a resource policy), but just creates new resources. Methods that create new resources generally take a MatchRule argument, allowing for future identification of the creator.

Our newDataStager operation is typical (it creates a new resource and initialises it with a dynamic policy that grants the caller of newDataStager the owner role):

public String newDataStager(MatchRule owner) {
	PBACUtils.validateOwner(owner, getCurrentUser(), "owner");

	// Create the new resource
	DataStager resource = new DataStager();

	// Register it with PBAC
	pdp.newProcess(MY_RESOURCE_TYPE, resource.ID);
	try {
		// Give the caller the 'owner' role
		pdp.addAccessControlRule(resourceID, owner);

		// Signal successful initialisation
		pdp.signal(resourceID, "init");

		return resource.ID;
	} finally {
		pdp.unlock(resourceID);
	}
}

The validateOwner method checks that the caller of newDataStager is matched by this policy as a sanity check (to prevent people from creating resources that they can't access). It also ensures that the rule grants the correct role (this is especially important if there are roles with greater access than owner, such as service-admin).

New resources start life in the locked state (preventing the user from doing anything with them until initialisation is complete). Since the PEP didn't lock it, it won't unlock it automatically, so the finally clause is required to do this. If the operation fails, the resource will be unlocked without receiving the "init" signal; the PDP will forget about it automatically in this case.

Before sending the "init" signal, we also need to give someone access to the resource. In this case, we grant the caller of newDataStager the owner process role. Note: If we sent the init signal first, and an error occured after that and before adding the new rule, we would get a new resource that no-one could access (except through the web admin interface). So, don't send the init signal until the point where the resource should continue to exist even if an exception is thrown.

If you try to invoke the newDataStager operation, PBAC will reject the request. To allow people to call it, edit the service's policy (not the data stagers's policy!) to add the new operation:

<state name="active">
		<operation name="echo">
			<process-role name="world"/>
		</operation>]]>
		<operation name="newDataStager">
			<process-role name="world"/>
		</operation>
</state>

Undeploy the old version using the web interface and deploy the new one. You should now be able to create new data stager objects. Of course, you may not want everyone to be able to create new data stagers. In that case, specify a different role instead of world. You will have to add a new rule using the web interface to grant someone this role.

Operations using the resource

Whenever a user invokes an operation on a resource, the PEP will check that the user is authorised and lock the resource for you. When your operation returns, the PEP will unlock it. Therefore, no-one else can perform operations on the resource during this time (the PDP will queue requests for around a minute by default before giving up).

A typical operation looks like this:

 public void deleteContents() {
	DataStager resource = getDataStagerFromContext();

	resource.deleteContents();

	pdp.signal(resource.ID, "delete");
 } 

Sending a signal may cause the state of the resource to change, affecting what operations can be called. In this case, the delete signal will cause the PDP to transition the resource to the empty state, from which the read operation is unavailable.

When a SOAP message arrives, the PBAC PEP extracts the resource ID from a WS-Addressing header element. It ensures that there is a signature covering both this header and the SOAP body, and passes the context and operation to the PDP to check that the signer is authorised to invoke the method. If the operation is authorised, the PEP stores the context in the Axis message context for use by the service.

The private getDataStagerFromContext method gets this resource context from the SOAP message context. There should always be a context by this point, because if the user didn't give one then PBAC would have used the service policy rather than the data stager policy to check the user's authorisation and the service policy should never allow deleteContents to be called. A typical implementation looks like this:

private DataStager getDataStagerFromContext() {
  	ProcessContext primaryContext = ProcessContextHelper.getProcessContext();
	String resourceID = primaryContext.getConversation();
	if (resourceID == null)
		throw new RuntimeException("No resource ID in message context (policy enforcement error)");
	return loadFromDatabase(resourceID);
}

Getting a resource's process state

Many services will maintain their own idea of a resource's state. However, sometimes it is useful to know the PBAC process state of a resource, or even make it available to clients. This operation does not send any signals, and thus does not change the state.

 public String getState() {
	DataStager resource = getDataStagerFromContext();
	return pdp.getCurrentState(resource.ID);
} 

Destroying a resource

There are two special states: UNINITIALISED-STATE and DESTROYED-STATE. If a resource is unlocked while in either of these two states, it is destroyed (causing PBAC to forget all about it). The destroyed state is used to remove a resource which is no longer needed, while unlocking an uninitialised resource indicates a failure while the service was setting up the resource.

To destroy a resource, send a signal such as destroy. The policy should cause the resource to transition to DESTROYED-STATE. When the PEP unlocks the resource after the operation completes, PBAC will forget about the resource.

Other PBAC operations

For a complete list of available PBAC operations, consult the JavaDoc reference.

Unlocking a resource during an operation

A service's operation is invoked by Axis only once PBAC has checked that the client is authorised to perform the operation. The resource is locked at this point.

Before returning, the service may send any number of events to the PDP, which may choose to update the state of the resource in response.

The fetch operation unlocks the resource, fetches the data from a remote URL, and then sets the state to FULL and returns. The purpose of this example is to show how the context can be unlocked during a long-running operation. Note that the resource itself must not be modified while it is unlocked; instead, we download to a temporary file. Once the data is ready, we lock the context to actually copy it in. "completeFetch" is an internal (fake) operation, used to reacquire the lock during the fetch operations.

Since the resource is unlocked, another operation could change its state (such as making it read-only or finishing it) while we fetch the data. In that case, the lockAndCheck operation would throw an exception (which is safe and reasonable). An alternative approach is to transition into a 'fetching' state at the start, from which only getState can be called. However, this makes the error handling more complex, as you must take care that the resource is not left in the 'fetching' state on error.

public void fetch(URL source) {
	DataStager resource = getDataStagerFromContext();

	pdp.unlock(resource.ID);

	File tempFile = source.fetchToTemp();	// Slow; resource unlocked

	try {
		pdp.lockAndCheck(resource.ID, "completeFetch");

		resource.store(tempFile);

		pdp.update(resource.ID, "fetch-complete");
	} finally (
		tempFile.unlink();
	}
}

Another alternative would be use lockForAdmin instead of lockAndCheck. This locks the resource without checking that it is in a suitable state. In this case you don't need to pass the user's identity, and the operation name is only used for display purposes (e.g., a notice in the admin page saying why the resource is locked). Use lockAndCheck if you want the operation to fail if the resource is now in the wrong state, or the user may have lost their privileges.

Delegation

Delegation operations (granting additional users access to an existing context) are invoked by the service. The client therefore calls a normal service operation, subject to the normal PBAC access control rules, to perform these operations.

For example, a data service might provide an addReaderRule operation which controls access to the reader role. The PBAC policy will determine who can call the addReaderRule operation on the service.

public void addReaderRule(MatchRule rule) {
	DataStager resource = getDataStagerFromContext();

	delegate.checkRole("reader");
	pdp.addAccessControlRule(resource.ID, rule);
}
  

You should also provide service operations that call PDP.removeAccessControlRule and PDP.getAccessControlRules to provide a full access control interface.

Discovering resources

Most services provide an operation to let users ask "Which resources can I access?". This is easily implemented using PBAC:

public String[] getResources() {
	return pdp.getResources(MyServiceInterface.MY_RESOURCE_TYPE, getCurrentUser(), null);
}

You may wish to convert the resources to EndpointReferenceTypes, so that they include the service address and any other meta-data (such as the user's label for the resource).