Simple Example 2

Description

Example 2 is similar to the previous example. The differences are that Thompson's data is added and a "category" attribute is added to the <salary> element. Also, the access control rules are described using group and role names, and a more complicated XPath expression is used for referring to objects. In this example, we explain how to use the graphical user interface to control the XACL processor.

The target XML document in this example is ex2_target.xml that contains two entries of personnel data (corresponding to the <personnel_info> elements) that consists of a <name> field, a <salary> field, and an optional <award> field as described below:

<personnel_info>
  <entry>
    <name>Johnson</name>
    <salary category="private" currency="USD">200,000</salary>
  </entry>
  <entry>
    <name>Thompson</name>
    <salary category="private" currency="USD">100,000</salary>
    <award category="private">Best Performance Award</award>
  </entry>
</personnel_info>

A set of access control rules (policy) for the above target XML document is described in the Access Control Rules figure below.

• The first rule says that people who belong to the "all" group are allowed to read any <name> field below the <entry> tag in a <personnel_info> element.
• The second rule says that any staff members included in the "personnel" group are allowed to read any fields categorized as "private" (i.e., whose "category" attribute is "private"), such as a <salary> field, provided the access is logged.
• The third rule says that one included in the "personnel" group who is authenticated to have a "Manager" role is allowed to update any fields categorized as "private", provided the access is logged.

<policy xmlns="http://www.trl.ibm.com/projects/xml/xacl">

<!-- ==================================================
  1. The "all" group can read name field.
 =================================================== -->
  <xacl>
    <object href="/personnel_info/entry/name"/>
    <rule>
      <acl>
        <subject>
          <group>all</group>
        </subject>
        <action name="read" permission="grant"/>
      </acl>
    </rule>
  </xacl>

<!-- ==================================================
  2. People in the personnel group can read any
     elements that are categorized as private,
     provided the access is logged.
 =================================================== -->
  <xacl>
    <object href="/personnel_info/entry/*[@category='private']"/>
    <rule>
      <acl>
        <subject>
          <group>personnel</group>
        </subject>
        <action name="read" permission="grant">
          <provisional_action timing="before" name="log"/>
        </action>
      </acl>

<!-- ==================================================
  3. Manager in the personnel group can write any
     elements that are categorized as private, provided
     the access is logged.
 =================================================== -->
      <acl>
        <subject>
          <role>Manager</role>
          <group>personnel</group>
        </subject>
        <action name="write" permission="grant">
          <provisional_action timing="before" name="log"/>
        </action>
      </acl>
    </rule>
  </xacl>
</policy>

How to Run the Example

Start XACL Visual Tool

Execute the following command with four system parameters specified (before executing the command, don't forget to change the active directory to data/xacldata ):

java -Dcom.ibm.xml.policy.xacl.rh=role_hierarchy.xml -Dcom.ibm.xml.policy.xacl.gh=group_hierarchy.xml -Dcom.ibm.xml.policy.tool.groupDefinitionPath=group.xml -Dcom.ibm.xml.policy.tool.bindTablePath=bind.xml com.ibm.xml.policy.tool.VisualTool

You should see the XACL Visual Tool:

The basic usage of this tool is as follows:

1. Open a target XML document.
2. Load an access request.
3. Click the "Start" button.
4. Then, access decisions (e.g. "grant" or "deny") on each element are displayed on the pane.

The detailed instructions are described below. Try out this simple example following them.

Open Target XML Document and Load Access Request

Execute the following steps:

1. Select the File/Open Target XML Document menu bar and open ex2_target.xml in the current directory. You will see the tree view of the target XML document in the right pane.
2. Select the File/Load Access Request menu bar and load ex2_request1.xml in the current XACL directory. You will see the access request information loaded in the left pane.

This access request is to ask whether or not Alice is allowed to read personnel_info element in ex2_target.xml.

Submit Access Requests

Click the "Start" button in the access request pane to invoke the XACL processor. The results should be:

The red elements such as <salary> indicate that the read actions on these elements are NOT allowed. The green elements such as <name> indicate that the read actions on these elements are allowed. Thus the access decisions in the above figure indicate that Alice is allowed to read the <name> field but not allowed to read other fields. This access decision is deduced from the first access control rule with the default group definition that Alice is in the "all" group.

The following Document Viewer is automatically popped up and it displays the target XML document (the original document) in the left pane and the transformed XML document in the right pane. We call the right pane an Initiator's View because it displays a certain set of elements that the initiator is allowed to read. As the above picture shows, the transformed document does not have privacy-sensitive fields such as a <salary> field. This transformation is conducted according to a set of access decisions displayed in red and green in the main window above.

Try out more requests:

• Load ex2_request2.xml and click the "Start" button. No subject is specified in the request (this may imply that an anonymous user is accessing) and the initiator with no subject is not allowed to read any fields.
• Load ex2_request3.xml and click the "Start" button. The initiator Bob is allowed to read all fields below the entry elements because Bob belongs to the "all" group and the "personnel" group.
• Load ex2_request4.xml and click the "Start" button. The initiator Bob is not allowed to WRITE the first <salary> field.
• Load ex2_request5.xml and click the "Start" button. The access request assumes that Bob is authenticated to have "Manager" role. This time, Bob with "Manager" role is allowed to write the <salary> field.

View the Associated Policy

Select the Tools/Policy Viewer menu bar to see the associated policy document. Please refer to Binding Target XML and Policy for further information about how the policy is associated with the target XML document.

Also you can select Tools/Status Viewer to see the status information of the target XML document. The status is associated with the target XML document in the same way as the policy.

Execute Mode and Query Mode

The XACL processor provides an element-wise update function on the target XML document. Here we change Thompson's <salary> field with a current value of "100,000". Load ex2_request6.xml. This access request asks whether or not Bob who has a "Manager" role can update Thompson's <salary> field with the value of "150,000". Note that "execute" radio button is checked. Then press "Start" button. You will see that the text node below Thompson's <salary> field is changed to the new value.

The "execute" mode orders the XACL processor to update the target element in case of write, create, and delete actions, and to generate the initiator's view in case of read action. The "query" mode only generates access decisions without performing any update operations on any data. Remember that whenever you make a query for write, create, and delete actions in "execute" mode, the target XML document and the status document is automatically updated without any prompts.

Provisional Actions

If you loaded the ex2_request3.xml or ex2_request6.xml and clicked the "start" button as described above, the status file (ex2_status.xml) has also been updated during the access execution. This is the side-effect of the "log" provisional action specified in the second and third rules that were selected as an winning rule in each access request. To see the status file, select the Tools/Status Viewer menu bar. The status pane has a <log> element that has stored the record of the execution of the previous accesses.

Note that whenever you start the XACL processor in "execute" mode, the status document is automatically updated without any prompts, if "log" provisional_action is specified in the corresponding access control rule.

Check the Initiator's View in Document Viewer

When you submit access requests with the read action in "execute" mode such as ex2_request1.xml, the right pane of the Document Viewer displays an initiator's view. In this case, the Initiator's View is identical to the file view.xml as follows:

<?xml version="1.0"?>
<!DOCTYPE personnel_info>
<personnel_info>
  <entry>
    <name>Johnson</name>
  </entry>
  <entry>
    <name>Thompson</name>
  </entry>
</personnel_info>

When "query" mode is selected or other actions (e.g. write) are selected, the Initiator's View is NOT displayed.

ex2_request7.xml is a modification of ex2_request5.xml. In ex2_request7.xml, Bob is assumed to play "Director" role, which is a upper role, and belong to "research" group, which is a subgroup of "personnel". By default, access control rules propagate upward along the role hierarhcy and downward along the group hierarchy. So the access decisions are the same as the ones for ex2_request5.xml.

Other Information

The policy file is implicitly associated with the target document in bind.xml. The binding information below means that when the target document is ex1_target.xml, then it should be bound to ex1_policy.xml and ex1_status.xml.

<bind_table>
  <bind>
    <target href="ex1_target.xml"/>
    <policy href="ex1_policy.xml"/>
    <status href="ex1_status.xml"/>
  </bind>
  <bind>
    <target href="ex2_target.xml"/>
    <policy href="ex2_policy.xml"/>
    <status href="ex2_status.xml"/>
  </bind>
...
</bind_table>

The Data Type Definition (DTD) file name can be specified as a target. Whenever the DTD file name of the target XML matches the DTD in bind.xml, the associated policy file in bind.xml is used. In the case where both the DTD and XML target files are specified in the bind file, the policy file associated with the XML target file is selected. You don't have to create a new binding file as long as you run the examples included in this package

You can change the path of the bind file. Please refer to Installation and Usage Guide for detailed information.

Group and Role Definition

The following group membership is defined for all the examples and sample applications in this package (each group contains members whose initial is the same with that of group name except for "all" group and several exceptions):

Above group membership is defined in group.xml as follows.

<group_definition>
<!-- ==============================
      Common group definition
 =============================== -->
  <group>
    <name>all</name>
    <member>Alice</member>
...
  </group>
    <name>admin</name>
    <member>Andrew</member>
    <member>Bob</member>
  </group>
...
</group_definition>

This definition means that the members of "all" group are Alice, and the members of "admin" group are Andrew and Bob. Each group can include one or more user IDs, but not any group names.

The above groups have a hierarical structure, which is defined in group_hierarchy.xml, where the "all" group has any other groups as subgroups.

Similarly, a role hierarchy used in this package is defined in role_hierarchy.xml.

Users can change the path of the above files when executing the Visual Tool. Please refer to Installation and Usage Guide for more details.