The Configuration Schema
PDP Configuration
Factory Configuration
Tying Factories to PDPs
Supporting a Configuration: ConfigurationStore
Examples
A Simple Example
Configuring a Module
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.
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 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.
<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
Note that as with a PDP's modules, any of the elements in a factory
may also be constructed using
A
A
The
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
An easy module to try loading is the
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.
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.
String or List
inputs. For complete examples, see the Examples section at the end of
this guide.
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.
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.
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.
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.
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.