Skip to content

Latest commit

 

History

History
160 lines (112 loc) · 10.4 KB

README.md

File metadata and controls

160 lines (112 loc) · 10.4 KB
Raw

Docker badge Build Status FOSSA Status

AuthzForce RESTful PDP

RESTful PDP API implementation, compliant with REST Profile of XACML 3.0. This is minimalist compared to AuthzForce server project as it does not provide multi-tenant PDP/PAP but only a single PDP (per instance). Therefore, this is more suitable for microservices, or, more generally, simple applications requiring only one PDP per instance.

In particular, the project provides the following (Maven groupId:artifactId):

  • org.ow2.authzforce:authzforce-ce-restful-pdp-cxf-spring-boot-server: a fully executable RESTful XACML PDP server (runnable from the command-line), packaged as a Spring Boot application or Docker image (see the Docker Compose example for usage).
  • org.ow2.authzforce:authzforce-ce-restful-pdp-jaxrs: pure JAX-RS implementation of a PDP service, that you can reuse as a library with any JAX-RS framework, especially other than Apache CXF, to provide your own custom RESTful PDP service.

Go to the releases page for specific release info: downloads (Linux packages), Docker image, release notes

Features

XACML PDP engine

See AuthzForce Core features for the XACML PDP engine's features.

REST API

Limitations

See AuthzForce Core limitations.

System requirements

Java (JRE) 17 or later.

Versions

See the change log following the Keep a CHANGELOG conventions.

License

See the license file.

Getting started

Launch the PDP with either Docker or the executable JAR as described in the next sections.

Using Docker

Git clone this github repository or download the Source code ZIP from the latest release and unzip it, then from the git clone / unzipped folder, go to the docker directory.

If you wish to use a different XACML Policy from the one provided, change the policyLocation parameter in the pdp/conf/pdp.xml (PDP configuration) file in that directory accordingly.

Then run: docker compose up -d, then docker compose logs to check the PDP is up and running.

(You can change the logging verbosity by modifying the Logback configuration file pdp/conf/logback.xml.)

Using the executable JAR

Get the latest executable jar from Maven Central with groupId/artifactId = org.ow2.authzforce/authzforce-ce-restful-pdp-cxf-spring-boot-server. The name of the JAR is authzforce-ce-restful-pdp-cxf-spring-boot-server-M.m.p.jar (replace M.m.p with the latest version).

Make sure it is executable (replace M.m.p with the current version):

chmod u+x authzforce-ce-restful-pdp-cxf-spring-boot-server-M.m.p.jar

Copy the content of that folder to the same directory.

If you wish to use a different XACML Policy from the one provided, change the policyLocation parameter in the pdp.xml (PDP configuration) file in that directory accordingly.

Then run the executable from that directory as follows (replace M.m.p with the current version):

$ ./authzforce-ce-restful-pdp-cxf-spring-boot-server-M.m.p.jar

If it refuses to start because the TCP listening port is already used (by some other server on the system), you can change that port in file application.yml copied previously: uncomment and change server.port property value to something else (default is 8080).

You know the embedded server is up and running when you see something like this (if and only if the logger for Spring classes is at least in INFO level, according to Logback configuration file mentioned down below) :

... Tomcat started on port(s): 8080 (http)

(You can change the logging verbosity by modifying the Logback configuration file logback.xml copied previously.)

Send an XACML Request to the PDP

Once the PDP is up and running, you can make a XACML request from a different terminal, for example using the XACML/JSON request in that folder (install curl tool if you don't have it already on your system):

$ curl --include --header "Content-Type: application/xacml+json" --data @IIA001/Request.json http://localhost:8080/services/pdp

Add --verbose option for more details. You should get a XACML/JSON response such as:

{"Response":[{"Decision":"Permit"}]}

Extensions

If you are missing features in AuthzForce, you can extend it with various types of plugins (without changing the existing code), as described on AuthzForce Core's wiki.

In order to use them, put the extension JAR(s) into an extensions folder in the same directory as the executable jar, already present if you followed the previous Getting started section. If the extension(s) use XML configuration (e.g. AttributeProvider), add the schema import into pdp-ext.xsd (import namespace only, do not specify schema location) and schema namespace-to-location mapping into catalog.xml. Then run the executable as follows (replace M.m.p with the current version):

$ java -Dloader.path=extensions -jar authzforce-ce-restful-pdp-cxf-spring-boot-server-M.m.p.jar

Example with MongoDBPolicyProvider extension

To use the Policy Provider for policies stored in MongoDB, 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 that is already included in AuthzForce RESTful PDP) is on the classpath, eg. in the extensions folder mentioned above, with and 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>mongodb-driver-legacy</artifactId>
	<!-- Set the version to whatever version is specified in authzforce-ce-core-pdp-testutils Maven POM. -->
         <version>${mongodb-driver-legacy.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).

More info.

Vulnerability reporting

If you want to report a vulnerability, please follow the GitHub procedure for private vulnerability reporting.

Support

If you are experiencing any issue with this project except for vulnerabilities mentioned previously, please report it on the GitHub Issue Tracker. Please include as much information as possible; the more we know, the better the chance of a quicker resolution:

  • Software version
  • Platform (OS and JDK)
  • Stack traces generally really help! If in doubt include the whole thing; often exceptions get wrapped in other exceptions and the exception right near the bottom explains the actual error, not the first few lines at the top. It's very easy for us to skim-read past unnecessary parts of a stack trace.
  • Log output can be useful too; sometimes enabling DEBUG logging can help;
  • Your code & configuration files are often useful.

If you wish to contact the developers for other reasons, use AuthzForce contact mailing list.

Contributing

See CONTRIBUTING.md.