Attribute Providers

These are PDP extensions that enable the PDP to get attributes from other sources than PEPs' requests. Such sources may be remote services, databases, etc. The AuthzForce project also provides a separate Attribute Provider example, for testing and documentation purposes only. If you wish to make your own attribute provider, read on the next section.

Making an Attribute Provider

The steps to make your own PDP Attribute Provider extension for AuthzForce go as follows:

1. Create a Maven project with jar packaging type.

2. Create an XML schema file with .xsd extension in the src/main/resources folder of your Maven project. Make sure this filename is potentially unique on a Java classpath, like your usual Java class names. One way to make sure is to use a filename prefix following the same conventions as the Java package naming conventions. In this schema file, define an XML type for your attribute provider configuration format. This type must extend AbstractAttributeProvider from namespace http://authzforce.github.io/xmlns/pdp/ext/3. You may use the schema of AuthzForce Test Attribute Provider (used for AuthzForce unit tests only) as an example. In this example, the XSD filename is org.ow2.authzforce.core.pdp.testutil.ext.xsd and the defined XML type extending AbstractAttributeProvider is TestAttributeProvider.

3. Copy the files bindings.xjb and catalog.xml from AuthzForce source code into the src/main/jaxb folder (you have to create this folder first) of your Maven project.

4. Add the following Maven dependency and build plugin configuration to your Maven POM:

      ...
      <dependencies>
       <dependency>
        <groupId>org.ow2.authzforce</groupId>
        <artifactId>authzforce-ce-core-pdp-api</artifactId>
        <version>12.1.0</version>
       </dependency>
       ...
      </dependencies> 
      ...
   
      <build>
       ...
       <plugins>
        <plugin>
         <groupId>org.jvnet.jaxb2.maven2</groupId>
         <artifactId>maven-jaxb2-plugin</artifactId>
         <version>0.13.0</version>
         <configuration>
          <debug>false</debug>
          <strict>false</strict>
          <verbose>false</verbose>
          <removeOldOutput>true</removeOldOutput>
          <extension>true</extension>
          <useDependenciesAsEpisodes>false</useDependenciesAsEpisodes>
          <episodes>
           <episode>
            <groupId>org.ow2.authzforce</groupId>
            <artifactId>authzforce-ce-pdp-ext-model</artifactId>
            <version>7.2.0</version>
           </episode>
          </episodes>
          <catalog>src/main/jaxb/catalog.xml</catalog>
          <bindingDirectory>src/main/jaxb</bindingDirectory>
          <schemaDirectory>src/main/resources</schemaDirectory>
         </configuration>
         <executions>
          <execution>
           <id>jaxb-generate-compile-sources</id>
           <phase>generate-sources</phase>
           <goals>
            <goal>generate</goal>
           </goals>
          </execution>
         </executions>
        </plugin>
        ...
       </plugins>
      </build>
      ...

   TODO: mention the issue with unwanted generation of xacml objectfactory, to be excluded from jar.

5. Run Maven generate-sources. This will generate the JAXB-annotated class(es) from the XML schema into the folder target/generated-sources/xjc, one of which corresponds to your attribute provider XML type defined in the second step, therefore has the same name and also extends org.ow2.authzforce.xmlns.pdp.ext.AbstractAttributeProvider class corresponding to AbstractAttributeProvider type in the XML schema. For example, in the case of the AuthzForce Test Attribute Provider aforementioned, the corresponding generated class is org.ow2.authzforce.core.pdp.testutil.ext.xmlns.TestAttributeProvider. In your case and in general, we will refer to it as your Attribute Provider Model Class.

6. Create your Attribute Provider factory and concrete implementation class (as in the Factory design pattern). The factory class must be public, and extend org.ow2.authzforce.core.pdp.api.CloseableDesignatedAttributeProvider.FactoryBuilder<APM>, where APM stands for your Attribute Provider Model Class; and the factory class must have a public no-argument constructor or no constructor. You may use the AuthzForce TestAttributeProvider implementation class (used for AuthzForce unit tests only) as an example. In this example, the static nested class Factory is the one extending CloseableDesignatedAttributeProvider.FactoryBuilder<TestAttributeProvider>. Such a class has a factory method getInstance(APM config, ...) (getInstance(TestAttributeProvider conf, ...) in the example) that, from an instance of your APM representing the XML input (org.ow2.authzforce.core.pdp.testutil.ext.xmlns.TestAttributeProvider in the example), creates an instance of your Attribute Provider implementation class (org.ow2.authzforce.core.pdp.testutil.ext.TestAttributeProvider in the example). Indeed, your Attribute Provider implementation class must implement the interface CloseableDesignatedAttributeProvider (package org.ow2.authzforce.core.pdp.api). To facilitate the implementation process, instead of implementing this interface directly, you should extend BaseDesignatedAttributeProvider (same package) in your implementation class, whenever possible. This class already implements the required interface. There are cases where it is not possible; for instance, since BaseDesignatedAttributeProvider is an abstract class, if your implementation needs to extend another abstract class, you have no choice but to implement the interface directly, because a Java class cannot extend multiple abstract classes. In any case, as mandated by the interface, your implementation class must implement the method get(attributeFQN, datatype, context) in charge of actually retrieving the extra attributes (TestAttributeProvider#get(...) in the example). The attributeFQN identifies an XACML attribute's fully qualified name, i.e. category, ID and optional Issuer that the PDP is requesting from your attribute provider; the datatype is the expected attribute datatype; and context is the request context, including the content from the current XACML Request and possibly extra attributes retrieved so far by other Attribute Providers.

7. When your implementation class is ready, create a text file org.ow2.authzforce.core.pdp.api.PdpExtension in folder src/main/resources/META-INF/services (you have to create the folder first) and put the fully qualified name of your implementation class on the first line of this file, like in the example from AuthzForce source code.

8. Run Maven package to produce a JAR from the Maven project.

Now you have an Attribute Provider extension ready for integration into AuthzForce Server, as explained in the next section.

#Integrating an Attribute Provider into AuthzForce

This section assumes you have an Attribute Provider extension in form of a JAR, typically produced by the process in the previous section. You may use AuthzForce PDP Core Tests JAR if you only wish to test the examples in this documentation. This JAR is available on Maven Central.

The steps to integrate the extension into the AuthzForce Server go as follows:

1. Import your attribute provider XML schema into the XML schema file, say pdp-ext.xsd used as input to BasePdpEngine constructor, using namespace only (no schemaLocation), like in the example from AuthzForce code with this schema import for AuthzForce TestAttributeProvider:

      <xs:import namespace="http://authzforce.github.io/core/xmlns/test/3" />

2. Add a uri element to XML catalog file catalog.xml used as input parameter to BasePdpEngine constructor, with your attribute Provider XML namespace as name attribute value, and, the location of your XML schema file within the JAR, as uri attribute value, prefixed by classpath:. For example, in the sample XML catalog from AuthzForce source code, we add the following line for AuthzForce TestAttributeProvider:

      <uri name="http://authzforce.github.io/core/xmlns/test/3" uri="classpath:org.ow2.authzforce.core.pdp.testutil.ext.xsd" />