Commit 6f71bb0d authored by cdanger's avatar cdanger

Merge branch 'develop' of https://github.com/authzforce/core.git into

develop

Conflicts:
	src/main/java/org/ow2/authzforce/core/pdp/impl/PdpConfigurationParser.java
parents 15f43c13 7b7ef8b5
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/dee3e6f5cdd240fc80dfdcc1ee419ac8)](https://www.codacy.com/app/coder103/authzforce-ce-core?utm_source=github.com&utm_medium=referral&utm_content=authzforce/core&utm_campaign=Badge_Grade)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/389/badge)](https://bestpractices.coreinfrastructure.org/projects/389)
# AuthZForce PDP Core (Community Edition)
Authorization PDP (Policy Decision Point) engine implementing the [OASIS XACML v3.0](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html).
......@@ -30,15 +31,16 @@ Java projects may use AuthZForce Core to instantiate an embedded Java PDP.
* **Attribute Datatypes**: you may extend the PDP engine with custom XACML attribute datatypes;
* **Functions**: you may extend the PDP engine with custom XACML functions;
* **Combining Algorithms**: you may extend the PDP engine with custom XACML policy/rule combining algorithms;
* **Attribute Providers**: you may plug custom attribute providers into the PDP engine to allow it to retrieve attributes from other attribute sources (e.g. remote service) than the input XACML Request during evaluation;
* **Attribute Providers a.k.a. PIPs** (Policy Information Points): you may plug custom attribute providers into the PDP engine to allow it to retrieve attributes from other attribute sources (e.g. remote service) than the input XACML Request during evaluation;
* **Request Filter**: you may customize the processing of XACML Requests before evaluation by the PDP core engine (e.g. used for implementing [XACML v3.0 Multiple Decision Profile Version 1.0 - Repeated attribute categories](http://docs.oasis-open.org/xacml/3.0/multiple/v1.0/cs02/xacml-3.0-multiple-v1.0-cs02.html#_Toc388943334));
* **Result Filter**: you may customize the processing of XACML Results after evaluation by the PDP engine (e.g. used for implementing [XACML v3.0 Multiple Decision Profile Version 1.0 - Requests for a combined decision](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-multiple-v1-spec-cd-03-en.html#_Toc260837890));
* **Root Policy Provider**: you may plug custom policy providers into the PDP engine to allow it to retrieve the root policy from specific sources (e.g. remote service);
* **Ref Policy Providers**: you may plug custom policy providers into the PDP engine to allow it to resolve `PolicyIdReference` or `PolicySetIdReference`;
* **Decision Cache**: you may extend the PDP engine with a custom XACML decision cache, allowing the PDP to skip evaluation and retrieve XACML decisions from cache for recurring XACML Requests;
* PIP (Policy Information Point): AuthzForce provides XACML PIP features in the form of extensions called *Attribute Providers*. More information in the previous list on *Extensibility points*.
## Versions
See the [change log file](CHANGELOG.md) according to the *Keep a CHANGELOG* [conventions](http://keepachangelog.com/).
See the [change log file](CHANGELOG.md) following the *Keep a CHANGELOG* [conventions](http://keepachangelog.com/).
## License
See the [license file](LICENSE.txt).
......@@ -53,16 +55,24 @@ If you want to use the experimental features (see previous section) as well, you
To get started using a PDP to evaluate XACML requests, instantiate a new PDP instance with one of the methods: `org.ow2.authzforce.core.pdp.impl.PdpConfigurationParser#getPDP(...)`. The parameters are:
1. Location of the configuration file (mandatory): this file must be an XML document compliant with the PDP configuration [XML schema](src/main/resources/pdp.xsd). You can read the documentation of every configuration parameter in that file.
1. Location of the XML catalog (optional, required only if using one or more XML-schema-defined PDP extensions): used to resolve the PDP configuration schema and other imported schemas/DTDs, and schemas of any PDP extension namespace used in the configuration file. You may use the [catalog](src/main/resources/catalog.xml) in the sources as an example. This is the one used by default if none specified.
1. Location of the PDP extensions schema file (optional, required only if using one or more PDP extensions): contains imports of namespaces corresponding to XML schemas of all XML-schema-defined PDP extensions to be used in the configuration file. Used for validation of PDP extensions configuration. The actual schema locations are resolved by the XML catalog parameter. You may use the [pdp-ext.xsd](src/test/resources/pdp-ext.xsd) in the sources as an example.
1. *confLocation*: location of the configuration file (mandatory): this file must be an XML document compliant with the PDP configuration [XML schema](src/main/resources/pdp.xsd). You can read the documentation of every configuration parameter in that file. If you don't use any XML-schema-defined PDP extension (AttributeProviders, PolicyProviders...), this is the only parameter you need, and you can use the simplest method `PdpConfigurationParser#getPDP(String confLocation)` to load your PDP. Here is an example of configuration:
Once you have a PDP instance. You can evaluate a XACML request by calling one of the `PDP#evaluate(...)` methods.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<pdp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://authzforce.github.io/core/xmlns/pdp/5.0" version="5.0.0">
<rootPolicyProvider id="rootPolicyProvider" xsi:type="StaticRootPolicyProvider" policyLocation="${PARENT_DIR}/policy.xml" />
</pdp>
```
This is a basic PDP configuration with basic settings and the root policy (XACML Policy document) loaded from a file `policy.xml` (see [this one](src/test/resources/conformance/xacml-3.0-from-2.0-ct/mandatory/IIA001/IIA001Policy.xml) for an example) located in the same directory as this PDP configuration file.
1. *catalogLocation*: location of the XML catalog (optional, required only if using one or more XML-schema-defined PDP extensions): used to resolve the PDP configuration schema and other imported schemas/DTDs, and schemas of any PDP extension namespace used in the configuration file. You may use the [catalog](src/main/resources/catalog.xml) in the sources as an example. This is the one used by default if none specified.
1. *extensionXsdLocation*: location of the PDP extensions schema file (optional, required only if using one or more XML-schema-defined PDP extensions): contains imports of namespaces corresponding to XML schemas of all XML-schema-defined PDP extensions to be used in the configuration file. Used for validation of PDP extensions configuration. The actual schema locations are resolved by the XML catalog parameter. You may use the [pdp-ext.xsd](src/test/resources/pdp-ext.xsd) in the sources as an example.
Once you have a instance of `PDP`, you can evaluate a XACML request by calling one of the `PDP#evaluate(...)` methods.
Our PDP implementation uses SLF4J for logging so you can use any SLF4J implementation to manage logging. As an example, we use logback for testing, so you can use [logback.xml](src/test/resources/logback.xml) as an example for configuring loggers, appenders, etc.
If you are using **Java 8**, make sure you set the following JVM system property is set before execution:
`javax.xml.accessExternalSchema = http`
If you are using **Java 8**, make sure the following JVM argument is set before execution:
`-Djavax.xml.accessExternalSchema=http`
## Support
......
......@@ -123,7 +123,7 @@ public final class PdpConfigurationParser
* We assume that this XML type is an extension of one the PDP extension base types, 'AbstractAttributeProvider' (that extends 'AbstractPdpExtension' like all other extension base
* types) in this case.
* @param catalogLocation
* location of XML catalog for resolving XSDs imported by the pdp.xsd (PDP configuration schema) and the extension XSD specified as 'extensionXsdLocation' argument (may be null)
* location of XML catalog for resolving XSDs imported by the extension XSD specified as 'extensionXsdLocation' argument (may be null if 'extensionXsdLocation' is null)
* @return PDP instance
* @throws java.io.IOException
* I/O error reading from {@code confLocation}
......@@ -176,7 +176,7 @@ public final class PdpConfigurationParser
* We assume that this XML type is an extension of one the PDP extension base types, 'AbstractAttributeProvider' (that extends 'AbstractPdpExtension' like all other extension base
* types) in this case.
* @param catalogLocation
* location of XML catalog for resolving XSDs imported by the pdp.xsd (PDP configuration schema) and the extension XSD specified as 'extensionXsdLocation' argument (may be null)
* location of XML catalog for resolving XSDs imported by the extension XSD specified as 'extensionXsdLocation' argument (may be null if 'extensionXsdLocation' is null)
* @return PDP instance
* @throws java.io.IOException
* I/O error reading from {@code confLocation}
......
......@@ -294,21 +294,21 @@
<attribute name="useStandardDatatypes" type="boolean" use="optional" default="true">
<annotation>
<documentation>Enable support for XACML core standard attribute
datatypes.
datatypes. If 'false', only dataypes specified in 'attributeDatatype' elements are available to the PDP, and therefore only these datatypes may be be used in policies.
</documentation>
</annotation>
</attribute>
<attribute name="useStandardFunctions" type="boolean" use="optional" default="true">
<annotation>
<documentation>Enable support for XACML core standard mandatory
functions.
functions. If 'false', only functions specified in 'function' elements are available to the PDP, and therefore only these functions may be be used in policies.
</documentation>
</annotation>
</attribute>
<attribute name="useStandardCombiningAlgorithms" type="boolean" use="optional" default="true">
<annotation>
<documentation>Enable support for XACML core standard combining
algorithms.
algorithms. If 'false', only algorithms specified in 'combiningAlgorithm' elements are available to the PDP, and therefore only these algorithms may be be used in policies.
</documentation>
</annotation>
</attribute>
......@@ -359,7 +359,9 @@
<documentation> Maximum depth of Variable reference chaining:
VariableDefinition1 -&gt; VariableDefinition2 -&gt; ...; where
'-&gt;' represents a
VariableReference. </documentation>
VariableReference. It is recommended to specify a value for this attribute in production for security/safety reasons.
Indeed, if not specified, no maximum is enforced (unlimited).
</documentation>
</annotation>
</attribute>
<attribute name="maxPolicyRefDepth" type="nonNegativeInteger" use="optional">
......@@ -367,7 +369,8 @@
<documentation>Maximum depth of Policy(Set) reference chaining:
PolicySet1 -&gt; PolicySet2 -&gt; ... -&gt; Policy(Set)N; where
'-&gt;' represents
a Policy(Set)IdReference.
a Policy(Set)IdReference. It is recommended to specify a value for this attribute in production for security/safety reasons.
Indeed, if not specified, no maximum is enforced (unlimited).
</documentation>
</annotation>
</attribute>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment