-
Notifications
You must be signed in to change notification settings - Fork 24
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:
#. Create a Maven project with jar
packaging type.
#. 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 <https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html>
. 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 <https://github.com/authzforce/core/blob/release-5.0.2/src/test/resources/org.ow2.authzforce.core.test.xsd>
(used for AuthZForce unit tests only) as an example. In this example, the XSD filename is
org.ow2.authzforce.core.test.xsd
and the defined XML type extending AbstractAttributeProvider
is
TestAttributeProvider
.
#. Copy the files bindings.xjb
and catalog.xml
from Authzforce source code <https://github.com/authzforce/core/blob/release-5.0.2/src/main/jaxb>
_ into the
src/main/jaxb
folder (you have to create this folder first) of your Maven project.
#. Add the following Maven dependency and build plugin configuration to your Maven POM:
.. code-block:: xml :linenos:
...
<dependencies>
<dependency>
<groupId>org.ow2.authzforce</groupId>
<artifactId>authzforce-ce-core-pdp-api</artifactId>
<version>7.1.1</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>3.4.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.
#. 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.xmlns.test.TestAttributeProvider
. In your case and in general, we will refer to it as your
Attribute Provider Model Class.
#. 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.CloseableAttributeProviderModule.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 TestAttributeProviderModule class <https://github.com/authzforce/core/blob/release-5.0.2/src/test/java/org/ow2/authzforce/core/test/custom/TestAttributeProviderModule.java>
_
(used for AuthZForce unit tests only) as an example. In this example, the static nested class Factory
is the one
extending CloseableAttributeProviderModule.FactoryBuilder<TestAttributeProvider>
. Such a class has a factory
method getInstance(APM configuration)
(getInstance(TestAttributeProvider conf)
in the example) that, from an
instance of your APM
representing the XML input (TestAttributeProvider
in the example), creates an instance
of your Attribute Provider implementation class (TestAttributeProviderModule
in the example). Indeed, your Attribute Provider implementation class must implement the interface CloseableAttributeProviderModule
(package org.ow2.authzforce.core.pdp.api
). To facilitate the implementation process,
instead of implementing this interface directly, you should extend BaseAttributeProviderModule
(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 BaseAttributeProviderModule
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(attributeGUID, attributeDatatype, context))
in charge of actually retrieving the extra attributes
(TestAttributeProviderModule#get(...)
in the example). The attributeGUID
identifies an XACML attribute
category, ID and Issuer that the PDP is requesting from your attribute provider; the attributeDatatype
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.
#. 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 <https://github.com/authzforce/core/blob/release-5.0.2/src/test/resources/META-INF/services/org.ow2.authzforce.core.pdp.api.PdpExtension>
_.
#. 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 <http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-core/5.0.2/authzforce-ce-core-5.0.2-tests.jar>
_.
The steps to integrate the extension into the AuthZForce Server go as follows:
#. 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 <TO BE FILLED>
_
with this schema import for Authzforce TestAttributeProvider
:
.. code-block:: xml :linenos:
<xs:import namespace="http://authzforce.github.io/core/xmlns/test/3" />
#. 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 <https://github.com/authzforce/server/blob/release-5.4.1/webapp/src/test/server.conf/authzforce-ce/catalog.xml>
_,
we add the following line for Authzforce TestAttributeProvider
:
.. code-block:: xml :linenos:
<uri
name="http://authzforce.github.io/core/xmlns/test/3"
uri="classpath:org.ow2.authzforce.core.test.xsd"/>