Before installing AX2E, you will need to have the following software installed:

• JDK 1.4 (Required)
• Apache Ant 1.6.x (Required)

In order to implement certain features, AX2E requires several libraries in the classpath. AX2E distribution has these libraries, except Saxon 8. Saxon is released under GNU GPL license, please download it following the descriptions below. Note, that the libraries are distributed with their own licenses. AXESCON Beta Tester license terms do not apply to them. The complete list of dependencies follows.

mail.jar from Java Mail API. AX2E was tested with version 1.3.3_01. This library is used only by RFC822NameAttribute implementation class. You can replaced your own custom class in order to avoid this dependency.

xercesImpl.jar, xml-apis.jar from Apache Xerces Java Parser. AX2E was tested with version 2.6.2. These libraries are used only when it's required to parse or write XML files, such as XACML Policies and Contexts. The core engine code doesn't use XML parsers.

xbean.jar, xbean_xpath.jar,jsr173_api.jar,resolver.jar,xmlpublic.jar from Apache XMLBeans project. AX2E uses XMLBeans package for all XML manipulations with XACML Policy and Context objects. XMLBeans is a very powerfull and popular XML mapping tool. AX2E uses XML to Java mapping of XACML 2.0 schemas, which were compiled by XMLBeans SchemaCompiler tool.
All XMLBeans-dependent code is isolated in the packages with names starting with "axescon.xacml.xb", i.e. three packages at this moment. These packages are not parts of core AX2E authorization engine code. Certainly, you can replace them with your own code, if dependency on XMLBeans is unwelcome. Also, if Policies are not stored as XML files, and XACML Context elements, such as Requests and Responses, are not passed as XML files, then XMLBeans package is not required. However, all AX2E samples come with XML files, therefore in order to execute them these libraries have to be in the classpath.

saxon8.jar from Saxon XQuery processor, please download it here. XMLBeans package uses Saxon version 8.1.1 for XPATH queries. This library is used only for XPATH support in XACML. If XPATH support is unnecessary, then Saxon 8 is not required.

spring.jar, commons-logging.jar from Spring Application Framework. AX2E comes with several samples to demonstrate compatibility with Spring framework. Spring is one of the best and most popular component framework. AX2E components can be configured using Spring. AX2E was tested with version 1.2.1. Spring is an optional component, and AX2E can be configured and used without it.
Spring is shipped with common-logging.jar (Apache Jakarta Commons project) and uses it for logging, therefore this library must be in the classpath whenever Spring is used.

junit.jar from jUnit. This is an optional component. AXESCON uses jUnit to test AX2E components. You don't need this library in order to deploy and use AX2E. It's only required to compile unit tests.

To start out, you'll need the AX2E binaries. Currently, AX2E is in Beta testing phase. You can become a Beta tester after accepting Beta Tester license terms. Please, send an e-mail to info@axescon.com for more information. Note, that AX2E Beta test package has a distributions beta-distr.zip with all depencies included, except Saxon.

Also, you can join AX2E Beta Tester User Group

	Subscribe to ax2e-beta
	Email:
	Browse Archives at groups.google.com

AX2E Beta test package come in one ZIP file. Unzip it to a directory of your choice. The following is the brief description of its content.

• classes - all pre-compiled classes of AX2E.
• conf - sample configuration files, used to configure AX2E engine.
• conformance2.0 - current version of OASIS XACML 2.0 Conformance Test suite. It can be downloaded from OASIS XACML TC web site, but this directory has more tests at this moment.
• gen14 - Java source codes generated by XMLBeans SchemaCompiler tool from XACML 2.0 Schemas.
• lib - required libraries, including dependencies.
• license - licenses, including third party software libraries.
• public-src - AX2E source codes are of two categories: public (open) and proprietary. During the beta test phase, only public source codes are distributed. This directory contains public source codes, i.e. AX2E API and Model classes. AX2E engine implementation is proprietary.
• schema_files - OASIS XACML 2.0 Schema files, which can also be downloaded from OASIS XACML TC web site.
• test - source codes for AX2E tests and samples.
• test-classes - compiled classes of for AX2E tests and samples.
• build.cmd, build.properties, build.xml - Windows build files for Ant.

Modify build.cmd file, i.e. set correct paths for JAVA_HOME and ANT_HOME environment variables.

Modify build.xml to set correct paths of libraries, which were mentioned in Dependencies section. Find <!-- Global Libraries --> comment. All library paths are under this line. For example,
<pathelement location="C:/work/saxonb8-1-1/saxon8.jar"/>
refers to Saxon 8 library. Currently, only Saxon's path has to be modified. Other libraries are in lib directory, and their paths are already set correctly.

At this point everything's ready for XACML 2.0 Conformance Test suite execution. Open command line window and change directory to where you unzipped Beta test package. Let's call it home-dir. Type in a command
build conformance
This should execute entire conformance test suite. Upon successfull execution, the console output should look similar to the following one:
L:\work\beta-distr>build conformance
L:\work\beta-distr>set JAVA_HOME=L:/j2sdk1.4.2_09
L:\work\beta-distr>set ANT_HOME=L:/work/apache-ant-1.6.5
L:\work\beta-distr>L:/work/apache-ant-1.6.5/bin/ant -Djdk.home=L:/j2sdk1.4.2_09 conformance
Buildfile: build.xml
compile.module.engine.production:
compile.module.engine.tests:
compile.module.engine:
compile.module.tests.production:
compile.module.tests.tests:
compile.module.tests:
conformance:
[java] start...
[java] conformance2.0 conf\axescon-xacml.properties
[java] ***
[java] skipped intentionally: policy schema validation failed
[java] skipped intentionally: policy schema validation failed ********************************
****************************************************************************************************
****************************************************************************************************
****************************************************************************************************
***********************
[java] skipped intentionally: OPTIONAL hierarchical resources
[java] skipped intentionally: OPTIONAL hierarchical resources
[java] skipped intentionally: OPTIONAL hierarchical resources *************
[java] ============ Results Summary ===
[java] 0 errors out of total 372
[java] 372 passed, rate: 100.0%
BUILD SUCCESSFUL
Total time: 20 seconds

All AX2E samples are in home-dir/test directory. All samples use axescon.xacml.test.LoopLoadTest class or its sub-classes. This class reads XACML Request files in a given directory, then it evaluates them against XACML Policy files in the same directory. Finally, it compares the results with expected XACML Response files. See its source code for more details. In order to evaluate the request, AX2E engine must be configured. Each sample has two ways of configuring the engine: with Spring framework or using the basic configurator. XACML 2.0 Conformance Test sample with Spring configurator is probably the best place to start exploring AX2E. Custom function, algorithm, and attribute type samples are intended to demonstrate how AX2E can be customized and extended. RBAC sample shows how to implement RBAC profile, it comes with working (!) XML sample files for role and permission policy sets.

XACML 2.0 Conformance Test Suite

XACML RBAC Profile 2.0 samples

Custom algorithm sample

Custom attribute type sample

Custom function sample

There's a very good book on programming, written by Niklaus Wirth. Its title is Algorithms + Data Structures = Programs. AX2E is a Java program, and it has the same formula: Model + Engine = AX2E. Model is a collection of Java classes, which represent such entities defined in OASIS XACML 2.0 standard as Policy and Request. Engine is a collection of Java classes, which implement XACML policy evaluation logic.

XACML 2.0 specification defines two schemas: Context and Policy schemas. AX2E data structures reflect these schemas. For example, XACML 2.0 Context Response element is modeled by axescon.xacml.model.ctx.Response Java interface. Its implementation is axescon.xacml.model.ctx.impl.ResponseImpl. AX2E more or less consistently follows this design, i.e. separation of interfaces and their implementations. Packages with names starting with axescon.xacml.model comprise Model, i.e. a collection of AX2E data structures.

Although XACML 2.0 is XML-based specification, it has a layer of abstraction, so that most parts of XACML implementation are not required to deal with actual XML documents. One notable exception is XPATH support. It's absolutely possible and not discouraged to use AX2E without actually having XACML Requests, Responses and even Policies as XML documents. For example, users can create axescon.xacml.model.ctx.impl.PolicyImpl objects from database records or LDAP trees, then manipulate these policies using Engine, without ever converting to or from XML documents.

AX2E was designed using component oriented approach. Its Engine is a bunch of co-operating components such as PolicyEvaluator, the main entry point to the engine. These components have external interfaces and internal implementations. For example, axescon.xacml.api.PolicyEvaluator is an interface and axescon.xacml.engine.PolicyEvaluatorImpl is a concrete implementation.

Each component has its own responsibilities and references to other components. Whenever there's something to be done beyond a given componet's scope, it employes services of other components. In component-oriented systems, components are created and initialized by an external entity, called framework or component manager. The framework is also responsible for linking components between each other. So, the components come to know their "team mates" only at the run time, when a system is up and running. Therefore, it's important to separate interfaces and implementations, so that component references are to interfaces. The concrete implementation instances are linked during the run-time. You can find a little more "theory" on the subject of component-oriented design here.

AX2E components should be compatible with any modern component framework. However, AX2E package is shipped pre-configured with two component managers: axescon.xacml.samples.BasicConfigurator and axescon.xacml.samples.SpringConfigurator. Note, that both classes are in axescon.xacml.samples package. The reason is that each application will probably have to integrate AX2E into its environment differently. These samples should help developers write custom component managers.

BasicConfigurator shows how to instantiate components and link them programmatically. For example, There's a component called AttributeSelectorEvaluator, its responsibility is to evaluate AttributeSelector elements of XACML 2.0 Policy Schema. This component needs a reference to another componenet, called XbAttrValueFactoryManager. So, our BasicConfigurator instantiates AttributeSelector, then sets a reference to XbAttrValueFactoryManager as it's shown below:

XBAttributeSelectorEvaluator ase = new XBAttributeSelectorEvaluator(false);
ase.setXbAttrValueFactoryManager(avfm);


BasicConfigurator is a very simple class, and it's easy to write similar custom configurators. However, we recommend to look at SpringConfigurator, which uses very popular component framework called Spring Application Framework. Spring Framework has many advanced features and makes it easier to configure AX2E to work in different environments. Spring stores all setup information in XML files(s). AX2E comes with sample configuration files in conf directory. Here's an excerpt from one of them:

<bean id="xbAttrValueFactoryManager"
class="axescon.xacml.xb.ctx.XBAttrValueFactoryManager"
singleton="true">
</bean>
...
<bean id="xbAttributeSelectorFactory"
class="axescon.xacml.xb.ctx.XBAttributeSelectorFactory"
singleton="true">
</bean>


This is the same AttributeSelector components, which was mentioned above. Replacing stock XBAttributeSelectorFactory with a custom one is just a matter of modification of the Spring application configuration file.

AX2E package has directory public-src, which contains Java source codes of Model and Engine API interfaces, as well as implementation classes of several components, such as PolicyStore. These interfaces can be extended and implemented to create a brand new XACML 2.0 implementation. AX2E samples package has additional source codes to help developers understand Model and Engine. AX2E package is shipped with a complete implementation of its own. The implementation source codes are proprietary, not public or open at this moment. However, you are free to replace any component with custom written classes.

Likely candidates for such a replacement are in axescon.xacml.xb.ctx package. As it was mentioned above, XACML 2.0 implementation doesn't necessarily have to deal with actual XML documents. However, AX2E package can create Requests, Responses, Policies and other elements of XACML from their XML representations. AX2E uses Apache XMLBeans library for this task. XMLBeans is a nice tool to manipulate XML from Java. However, if you don't like it, you can throw it out, and write your own components using, for instance, StAX, another emerging XML to Java API.