Policy Providers

(draft)

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/5.0} StaticRefPolicyProvider	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/9.0.1 (and later)	org.ow2.authzforce.core.pdp.impl.policy.CoreRefPolicyProviderModule
{http://authzforce.github.io/core/xmlns/test/3} MongoDBBasedPolicyProvider	Gets policies from a MongoDB database.	classpath:org.ow2.authzforce.core.pdp.testutil.ext.xsd	org.ow2.authzforce/authzforce-ce-core-pdp-testutils/9.0.1 (and later)	org.ow2.authzforce.core.pdp.testutil.ext.MongoDBRefPolicyProviderModule

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 BasePdpEngine.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 BasePdpEngine.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, add a uri entry mapping the namespace to the actual XML schema URL - see XML schema URL column in table above for examples - to the XML catalog file, e.g. catalog.xml, 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, sets the refPolicyProvider element to the wanted Policy Provider's XML type - see ID column in previous table - and the rootPolicyProvider element to type {http://authzforce.github.io/core/xmlns/pdp/5.0}StaticRefBasedRootPolicyProvider in order to make the PDP's root policy provided by the refPolicyProvider 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 org.ow2.authzforce.core.pdp.impl.BasePdpEngine getInstance(final String confLocation, final String catalogLocation, final String extensionXsdLocation) with aforementioned pdp.xml, catalog.xml and pdp-ext.xsd as confLocation, catalogLocation, and extensionXsdLocation arguments respectively.

Implementing new Policy Providers

If the Policy Providers listed in table above do not satisfy you, you may implement your own. TODO: explain the process