Policy Providers

Policy Providers are PDP extensions to get policies for evaluation from various kinds of policy repositories: local filesystem, remote services, databases, etc.

Out-of-the-box Policy Providers

The following Policy Providers are provided out-of-the-box in open source:

ID	Description	XML schema URL	Required Maven dependency	Implementation class
{http://authzforce.github.io/core/xmlns/pdp/7.0} StaticPolicyProvider	Gets policies from a list of URLs to XACML Policy(Set) documents, each URL using any of the following schemes: http, https, file, jar, classpath.	classpath:pdp.xsd	org.ow2.authzforce/authzforce-ce-core-pdp-engine/14.0.0 (and later)	org.ow2.authzforce.core.pdp.impl.policy.CoreStaticPolicyProvider
{http://authzforce.github.io/core/xmlns/test/3} MongoDBBasedPolicyProviderDescriptor	Gets policies from a MongoDB database.	classpath:org.ow2.authzforce.core.pdp.testutil.ext.xsd	org.ow2.authzforce/authzforce-ce-core-pdp-testutils/14.0.0 (and later)	org.ow2.authzforce.core.pdp.testutil.ext.MongoDbPolicyProvider

Column info:

• ID: XML {namespace}type to use to instantiate the extension in a PDP configuration file. The namespace is used in the PDP extensions schema to enable the extension, i.e. in the schema whose location is passed as extensionXsdLocation argument to PdpEngineConfiguration#getInstance(...), you must have an entry: <xs:import namespace="http://authzforce.github.io/core/xmlns/test/3" /> (where xs would be the prefix associated to namespace http://www.w3.org/2001/XMLSchema), except for extensions implemented in package org.ow2.authzforce.core.pdp.impl;
• XML schema URL: uri value to be used in the XML catalog entry, i.e. in the XML catalog whose location is passed as catalogLocation argument to PdpEngineConfiguration#getInstance(...), you must have an entry: <uri name="{the XML namespace in *ID* column}" uri="{the XML schema location}" /> , except for extensions implemented in package org.ow2.authzforce.core.pdp.impl. Follow the link to go to the XML schema where the extension's configuration format (XML type definition) is defined.
• Implementation class: Java implementation class.

Using Policy Providers

If and only if the implementation class of the Policy Provider you want to use is in package org.ow2.authzforce.core.pdp.impl, jump to step 4 (skip 1 to 3).

1. Make sure the JAR corresponding to the Required Maven dependency in table above for the Policy Provider you wish to use, and its own dependencies, if any, are on the classpath.
2. Import the schema of the Policy Provider into the extension activation XSD file, e.g. pdp-ext.xsd, by adding a XSD import with namespace attribute only for each one - see ID column in table above for examples - like in this example. This extension activation XSD file is an XML schema that imports the schemas of all extensions you want to enable on the PDP, except for the ones in org.ow2.authzforce.core.pdp.impl. Therefore, if all extensions are in org.ow2.authzforce.core.pdp.impl package, you do not need such a file; else if you don't have such a pdp-ext.xsd yet, just create one from the example.
3. For each extension's schema imported in pdp-ext.xsd, in the XML catalog file, e.g. catalog.xml, add a uri entry mapping the namespace to the actual XML schema URL - see XML schema URL column in table above for examples - like in this example. If you don't have an XML catalog yet, just create one from the example.
4. In PDP configuration file, e.g. pdp.xml, set the policyProvider element to the wanted Policy Provider's XML type - see ID column in previous table - and the rootPolicyRef element to the ID (PolicyId or PolicySetId) of the PDP's root policy provided by the policyProvider itself, like in this example. If you don't have a PDP configuration file, just create one from the example.
5. Finally, in your code, in order to instantiate a PDP engine, use method PdpEngineConfiguration#getInstance(confLocation, catalogLocation, extensionXsdLocation) with aforementioned pdp.xml, catalog.xml and pdp-ext.xsd as confLocation, catalogLocation, and extensionXsdLocation arguments respectively; then use the result as configuration argument to BasePdpEngine(configuration) constructor.

More info on the MongoDbPolicyProvider

The MongoDbPolicyProviderTest is the reference on how to use this policy provider.

Prepare the policies in the MongoDB collection

The MongoDbPolicyProviderTest#setUpBeforeClass() method gives an example of how to upload a Policy or PolicySet to MongoDB properly so that it can be retrieved successfully by the policy provider. So if you are uploading policies using Java, feel free to reuse the code. If you are using another programming language, make sure you upload policies in a collection of JSON objects with the following fields (key-value pairs):

• "id" (string): the Policy(Set) ID
• "version" (string): the Policy(Set) version
• "type" (string): the Policy(Set) type, i.e. {urn:oasis:names:tc:xacml:3.0:core:schema:wd-17}Policy for XACML 3.0 Policy, or {urn:oasis:names:tc:xacml:3.0:core:schema:wd-17}PolicySet for a XACML 3.0 PolicySet
• "content" (string): the actual Policy(Set)'s XML document as string (plain text)

Installing and configuring the Policy Provider

Please make sure the JAR with the MongoDB policy provider, i.e. the authzforce-ce-core-pdp-testutils module (in the same version as authzforce-ce-core-pdp-engine) is on the classpath with all its required dependencies. The main dependencies (looking at the pom of pdp-testutils module) in Maven terms are:

<dependency>
         <groupId>org.jongo</groupId>
         <artifactId>jongo</artifactId>
	 <!-- Set the version to whatever version is specified in authzforce-ce-core-pdp-testutils Maven POM.  -->
         <version>${jongo.version}</version>
</dependency>
<dependency>
         <groupId>org.mongodb</groupId>
         <artifactId>mongo-java-driver</artifactId>
	<!-- Set the version to whatever version is specified in authzforce-ce-core-pdp-testutils Maven POM. -->
         <version>${mongo-java-driver.version}</version>
</dependency>

These dependencies have dependencies as well, so make sure to include them all, if not already on the classpath. (There is a way to assemble all jars in a dependency tree automatically with Maven.)

Then do steps 2 to 4 of Using Policy Providers, that is to say:

1. Add this import to PDP extensions schema (pdp-ext.xsd) to allow using the extension(s) from the authzforce-ce-core-pdp-testutils module in PDP configuration:

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

2. Add an entry to the XML catalog (catalog.xml) to locate the schema corresponding to this namespace:

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

3. Add the policyProvider element to the PDP configuration (pdp.xml), using the new namespace above, like in this example (follow the link).

Making new Policy Providers

If the Policy Providers listed in table above are not enough for you, you may provide your own in a JAR - e.g. built by Maven - expected to be on the classpath and expected to contain the following:

1. An XML schema (XSD) file that defines your Policy Provider's configuration format, i.e. XML type, like the ones in XML schema URL column of table above. This XML type must extend {http://authzforce.github.io/xmlns/pdp/ext/3}AbstractPolicyProvider, e.g. MongoDBBasedPolicyProviderDescriptor in org.ow2.authzforce.core.pdp.testutil.ext.xsd. Make sure the XSD file imports schema namespace http://authzforce.github.io/xmlns/pdp/ext/3 at least, and its name/path is unique on the classpath by using the name or folder of your Java implementation package as prefix, following the same conventions as the Java package naming conventions; e.g. if the package is com.mydomain.mysubdomain, your XSD location inside the JAR should be something like com.mydomain.mysubdomain.my-authzforce-extensions.xsd or com/mydomain/mysubdomain/my-authzforce-extensions.xsd. If using Maven to build the JAR, this file should be located in your Maven project at src/main/resources/com.mydomain.mysubdomain.my-authzforce-extensions.xsd or src/main/resources/com/mydomain/mysubdomain/my-authzforce-extensions.xsd depending on your favorite naming convention.

2. The JAXB-annotated classes derived from the previous XSD. One of these classes must extend org.ow2.authzforce.xmlns.pdp.ext.AbstractPolicyProvider, let's call it the AbstractPolicyProvider extension class. If using Maven to build the JAR, you may generate these XSD-derived JAXB classes automatically by copying the files bindings.xjb and catalog.xml from there to a specific folder of your Maven project, say src/main/jaxb (you have to create it first); and adding these lines (change values where necessary to match your setup) to the Maven POM:

   ...
      <dependencies>
       <dependency>
        <groupId>org.ow2.authzforce</groupId>
        <artifactId>authzforce-ce-core-pdp-api</artifactId>
        <!-- WARNING: make sure this version matches the version used by your authzforce-ce-core-pdp-engine JAR version, as mentioned in its Maven POM file. -->
        <version>16.0.0</version>
        <scope>provided</scope>
       </dependency>
       ...
      </dependencies> 
      ...
   
      <build>
       ...
       <plugins>
       ...
       <plugin>
            <groupId>org.jvnet.jaxb2.maven2</groupId>
            <artifactId>maven-jaxb2-plugin</artifactId>
            <version>0.14.0</version>
            <configuration>
               <!-- debug=true will generate JAXBDebug class. More info: https://github.com/highsource/maven-jaxb2-plugin/wiki/Miscellaneous -->
               <debug>false</debug>
               <strict>false</strict>
               <verbose>true</verbose>
               <removeOldOutput>true</removeOldOutput>
               <extension>true</extension>
               <useDependenciesAsEpisodes>true</useDependenciesAsEpisodes>
               <catalog>src/main/jaxb/catalog.xml</catalog>
               <bindingDirectory>src/main/jaxb</bindingDirectory>
               <bindingIncludes>
                  <include>bindings.xjb</include>
               </bindingIncludes>
               <schemaDirectory>src/main/resources</schemaDirectory>
            </configuration>
            <executions>
    	<execution>
    	    <goals>
    		<goal>generate</goal>
    	    </goals>
    	</execution>
            </executions>
         </plugin>
        ...
       </plugins>
      </build>
      ...

   If your Policy Provider's XSD imports extra namespaces besides http://authzforce.github.io/xmlns/pdp/ext/3, you need to modify the catalog.xml (add the uri entry mapping the namespace to corresponding XSD URL) and maven-jaxb2-plugin configuration above (adding an episode for the Maven artifact that provides the corresponding JAXB classes) to tell the XSD-to-Java generation tool where to find the extra corresponding XML schemas and JAXB-derived classes. More info. Finally, run Maven generate-sources to generate the JAXB-annotated class(es) into the folder target/generated-sources/xjc.

3. The Policy Provider factory and concrete implementation classes (as in the Factory design pattern). The factory class must be public, and extend CloseablePolicyProvider.Factory<AEC>, where AEC is the previously mentioned AbstractPolicyProvider Extension Class; and the factory class must have either a public no-argument constructor or no constructor. See MongoDbPolicyProvider class for an example. In this example, the static nested class Factory is the one extending CloseablePolicyProvider.Factory<AEC> where AEC is org.ow2.authzforce.core.pdp.testutil.ext.xmlns.MongoDBBasedPolicyProviderDescriptor. The factory class method CloseablePolicyProvider.Factory#getInstance(...) creates an instance of CloseablePolicyProvider (e.g. MongoDbPolicyProvider) from the AEC instance (e.g. MongoDBBasedPolicyProviderDescriptor), i.e. XML configuration. Whenever possible, to facilitate the implementation, your CloseablePolicyProvider implementation class may extend abstract class BaseStaticPolicyProvider which already implements CloseablePolicyProvider with stub implementation. In any case, as mandated by the CloseablePolicyProvider interface, your implementation class must implement the method get(policyType, policyId...) in charge of actually retrieving the policy, given . For your implementation classes, you need authzforce-ce-core-pdp-api dependency (and indirect dependencies). If using Maven, use this dependency info in your POM:

       <dependency>
        <groupId>org.ow2.authzforce</groupId>
        <artifactId>authzforce-ce-core-pdp-api</artifactId>
        <!-- WARNING: make sure this version matches the version used by your authzforce-ce-core-pdp-engine JAR version, as mentioned in its Maven POM file. -->
        <version>16.0.0</version>
        <scope>provided</scope>
       </dependency>

4. When your Policy Provider implementation class is ready, you create a configuration file to enable AuthzForce extension manager to discover this new extension dynamically at runtime. AuthzForce extension mechanism is based on Java native extension mechanism. In this regard, the PdpExtension interface is the SPI, and your Policy Provider implementation must be registered as one of the Service Provider for this SPI. In short, all you have to do is create a configuration file org.ow2.authzforce.core.pdp.api.PdpExtension in folder src/main/resources/META-INF/services (you may have to create the folder first) and put the fully qualified name of your implementation class on the first line of this file (or a new line if there are others already there), like in the example from AuthzForce source code. More info.

5. Build your project JAR with Maven, then you may use it on the PDP.