Sun's XACML Implementation

Run-Time Configuration Guide for Version 1.2

Last Updated: July 11, 2004

 Introduction

 The Configuration Schema
   PDP Configuration
   Factory Configuration
   Tying Factories to PDPs

 Supporting a Configuration: ConfigurationStore

 Examples
   A Simple Example
   Configuring a Module

Introduction

This guide describes the run-time configuration system, and the associated XML schema introduced in the 1.2 release. The goal of this system is to provide a simple, lightweight mechanism that lets anyone using the SunXACML code optionally include some degree of dynamic configuration for factories and PDPs. For reasons of security and extensibility, this system is never used "automatically" (eg, simply by setting a property). Instead, programmers must decide to support this in their code. Luckily, this is fairly easy.

Note that because this system is not tightly coupled with the rest of the SunXACML code, nor is it ever automatically invoked, you are still free to define your own configuration mechanisms. In fact, you may find that for a given application you want to re-use the configuration schema, but support it in a custom manner in your code. That's fine. The idea here is simply to provide a set of common, convenience mechanisms that are available for everyone. In practice, the functionality provided here is probably enough for most applications.

This guide is split into two main sections. The first section describes the configuration schema, and therefore how you write configuration descriptions. The second part describes a new class used for loading and managing configurations. If you need more help you should look at the schema itself, the javadocs, and the samples available in the release package, which make use of this run-time configuration system. This guide assumes you have some familiarity with XACML and SunXACML, and specifically that you understand the finder system and the various factories. These are described in detail in the Programmer's Guide.

The Configuration Schema

Configurations are defined through a relatively simple XML encoding, specified by an XML schema. Basically, a configuration defines a collection of PDPs and Factories. A PDP configuration is defined by the set of modules it contains, and how those modules are configured. A Factory is defined by the datatypes, algorithms, or functions it supports, and how they are configured. The schema describing the configuration format used in the 1.2 release is available here.

At its root, a configuration description starts with the config tag, which contains some number of PDP and factory descriptions. The config tag also requires you to identify a default for each of these things:

     <config defaultPDP="pdp" defaultAttributeFactory="attr"
             defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
       ...
     </config>
  
Full examples are found at the end of this document.

PDP Configuration

A pdp entry takes the form of a name, and the set of modules it contains:
  <pdp name="pdp1">
    ...
  </pdp>
  
Each module in a PDP is specified using the appropriate kind of tag (attributeFinderModule, policyFinderModule, or resourceFinderModule), and names the class that should actually be loaded (where the class is an implementation of com.sun.xacml.finder.AttributeFinderModule, com.sun.xacml.finder.PolicyFinderModule, or com.sun.xacml.finder.ResourceFinderModule, respectively). For instance, this element
  <attributeFinderModule class="com.sun.xacml.finder.impl.CurrentEnvModule"/>
  
specifies an AttributeFinderModule to load. Note that the class must be available in your classpath.

With all classes you load through this configuration system you may specify arguments to the class' constructors. In the above example, the default (empty) constructor is used. You may also specify Strings and Lists parameters, as in:

  <policyFinderModule class="com.sun.xacml.finder.impl.FilePolicyModule">
    <list>
      <string>policy1.xml</string>
      <string>policy2.xml</string>
    </list>
  </policyFinderModule>
  
This builds a List of Strings, and constructs a com.sun.xacml.finder.impl.FilePolicyModule using a constructor that takes a single java.util.List. Your modules may take any number of arguments they like, but if the provided paramters don't match one of the constructors of the class being loaded, then an exception is thrown and loading the configuration fails.

Factory Configuration

Like PDPs, factory definitions start with a name, and contain some set of appropriate classes. Unlike the PDP elements, factory elements may also contain an attribute that says to start with the standard functionality:
  <attributeFactory name="attrFactory1" useStandardDatatypes="true">
    ...
  </attributeFactory>
  
In this case, the attribute factory is pre-configured with support for the standard datatypes. This is useful if you want a factory that supports just a few things beyond the standard supported types.

Each factory is defined by the things it supports. An attributeFactory element contains datatype elements that supply a class and an identifier, where the class is an implementation of com.sun.xacml.attr.AttributeProxy:

  <datatype class="com.sun.xacml.attr.proxy.BooleanAttributeProxy"
            identifier="http://www.w3.org/2001/XMLSchema#boolean"/>
  
A combiningAlgFactory contains algorithm elements that specify a class, where the class is an implementation of com.sun.xacml.combine.PolicyCombiningAlgorithm or com.sun.xacml.combine.RuleCombiningAlgorithm:
  <algorithm class="com.sun.xacml.combine.FirstApplicablePolicyAlg"/>
  
If you start with a factory supporting the standard datatypes or algorithms, of course, you don't need to specify any standard elements (like the datatype and algorithm shown above). Typically, this feature is used to augment standard implementations by adding some new types that you have defined. Note that it's illegal for a factory to have more than one element with the same identifier. If you try to specify such a factory then an exception is thrown and the confoguration is invalid.

Note that as with a PDP's modules, any of the elements in a factory may also be constructed using String or List inputs. For complete examples, see the Examples section at the end of this guide.

A functionFactory is a little more complex. Each functionFactory contains three optional sections (target, condition, and general), where the functions here follow the standard "superset" relationship described in the javadocs (ie, a condition function is also available through the general collection, and a target function is available in all three collections):

    <functionFactory name="func" useStandardFunctions="true">
      <target>
        ...
      </target>
      <condition>
        ...
      </condition>
      <general>
        ...
      </general>
    </functionFactory>
  
Each section contains function, abstractFunction, and functionCluster elements.

A function element identifies a single function, specifying a class of type com.sun.xacml.cond.Function:

  <function class="TimeInRangeFunction"/>
  <function class="com.sun.xacml.cond.EqualFunction">
    <string>urn:oasis:names:tc:xacml:1.0:function:string-equal</string>
  </function>
  
An abstractFunction identifies a single abstract function, specifying a class of type FunctionProxy:
  <abstractFunction class="com.sun.xacml.cond.MapFunctionProxy"
                    identifier="urn:oasis:names:tc:xacml:1.0:function:map"/>
  
A functionCluster is a convenience element that lets you specify a group of functions (though not abstract functions) through an implementation of com.sun.xacml.cond.cluster.FunctionCluster:
  <functionCluster class="com.sun.xacml.cond.cluster.EqualFunctionCluster"/>
  

Tying Factories to PDPs

The one obvious missing piece of functionality is a way to specify which factories are used by a given PDP. Unfortunately, this isn't supported right now. Basically, it will require some API changes to make this work, and since the 1.2 release tried to leave the APIs as stable as possible, this feature was pushed off to 2.0. In the 2.0 release, the related APIs will have to change (since the code will be supporting different versions of XACML), so this feature will be added at that point.

Supporting a Configuration: ConfigurationStore

Now that you've seen how a configuration is written, you need to understand how to use that configuration in your code. Actually, this is much easier than writing the configuration itself. In the 1.2 release a new class called ConfigurationStore was introduced that takes care of handling all your configurations.

The ConfigurationStore is constructed directly, either using the default constructor, or by supplying a File that names the configuration data that is backing the store. In the case of the default constructor, ConfigurationStore tries to use the property com.sun.xacml.PDPConfigFile to get the file that contains the configuration data. This means you can either specify the configuration file explicitly

    File configFile = new File("config.xml");
    ConfigurationStore store = new ConfigurationStore(configFile);
  
or rely on a run-time property to supply the filename
    ConfigurationStore store = new ConfigurationStore();
  
Note that in the 1.2 release you can only work with file-based configurations. In the 2.0 release this mechanism will be extended to support different retrieval mechanisms.

Once the store is created, there are accessor methods to ask for PDPs and factories. You can ask for a specific named element (as identified by the name attribute on the pdp or factory element tag), or for a default element. You can also ask for the identifiers for all supported elements. In this way, you pick which pieces of the configuration you want to use any parts of your code.

In addition to querying for specific factory configurations, the ConfigurationStore also provides a convenience method called useDefaultFactories, which (as the name suggests) sets the system-wide default factories to the defaults specified in the configuration. For many people, this is all the functionality they need for factory handling. Note that since the factory functionality will change in 2.0 (so factories can be paired with PDPs), this method will become less useful in the next major release.

Examples

What follows here are a few simple examples that demonstrate most of the features in this configuration system. For more examples, you should look in the 1.2 release and in the conformance package, both of which contain examples of how to use configurations.

A Simple Example

Here is a basic example that provides a technically correct, though functionally useless configuration:
  <config defaultPDP="pdp" defaultAttributeFactory="attr"
          defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
    <pdp name="pdp"/>
    <attributeFactory name="attr" useStandardDatatypes="false"/>
    <combiningAlgFactory name="comb" useStandardAlgorithms="false"/>
    <functionFactory name="func" useStandardFunctions="false"/>
  </config>
  
Note that it provides a single PDP with no modules, and a set of factories that support no features. A slightly more useful configuration might look like this:
  <config defaultPDP="pdp" defaultAttributeFactory="attr"
          defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
    <pdp name="pdp">
      <attributeFinderModule class="com.sun.xacml.finder.impl.CurrentEnvModule"/>
      <attributeFinderModule class="com.sun.xacml.finder.impl.SelectorModule"/>
    </pdp>
    <attributeFactory name="attr" useStandardDatatypes="true"/>
    <combiningAlgFactory name="comb" useStandardAlgorithms="true"/>
    <functionFactory name="func" useStandardFunctions="true"/>
  </config>
  
This provides default factories that support all standard features, and configures the default PDP with two commonly useful finder modules. You might extend this example even further by providing support for the TimeInRangeFunction which isn't in the standard FunctionFactory yet because it won't be part of the specification until 2.0:
  <config defaultPDP="pdp" defaultAttributeFactory="attr"
          defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
    <pdp name="pdp">
      <attributeFinderModule class="com.sun.xacml.finder.impl.CurrentEnvModule"/>
      <attributeFinderModule class="com.sun.xacml.finder.impl.SelectorModule"/>
    </pdp>
    <attributeFactory name="attr" useStandardDatatypes="true"/>
    <combiningAlgFactory name="comb" useStandardAlgorithms="true"/>
    <functionFactory name="func" useStandardFunctions="true">
      <condition>
        <function class="TimeInRangeFunction"/>
      </condition>
    </functionFactory>
  </config>
  
Simple, huh? What you see here is a fully functional configuration that you could start using to define your XACML environment.

Configuring A Module

The final of the three previous examples shows a fairly useful configuration, but it's missing a key component: a PolicyFinderModule. Without one of these modules, your PDP will never be able to fetch policies. You can, of course, load the above configuration and then add other modules in your code, or you can add the module directly to your configuration.

An easy module to try loading is the FilePolicyModule example module. This finder module provides policies from the local filesystem, and so it needs to be pre-configured with policy files. This is easily done in the configuration (as shown before in the schema section):

  <config defaultPDP="pdp" defaultAttributeFactory="attr"
          defaultCombiningAlgFactory="comb" defaultFunctionFactory="func">
    <pdp name="pdp">
      <attributeFinderModule class="com.sun.xacml.finder.impl.CurrentEnvModule"/>
      <attributeFinderModule class="com.sun.xacml.finder.impl.SelectorModule"/>
      <policyFinderModule class="com.sun.xacml.finder.impl.FilePolicyModule">
        <list>
          <string>policy1.xml</string>
          <string>policy2.xml</string>
        </list>
      </policyFinderModule>
    </pdp>
    <attributeFactory name="attr" useStandardDatatypes="true"/>
    <combiningAlgFactory name="comb" useStandardAlgorithms="true"/>
    <functionFactory name="func" useStandardFunctions="true">
      <condition>
        <function class="TimeInRangeFunction"/>
      </condition>
    </functionFactory>
  </config>
  


Send comments, questions, and corrections to seth proctor.

Copyright 2003-2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

Sun, Sun Microsystems, the Sun Logo, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.