Commit a2a64f84 authored by cdanger's avatar cdanger
Browse files

- Improved README on new features

parent b26e299c
......@@ -23,7 +23,7 @@ You may build the project and generate the JAR as follows from your local copy o
Note that you must use Java 8 to run Maven when building the project.
### Dependency management
1. No SNAPSHOT dependencies on "develop" and obviously "master" branches
No SNAPSHOT dependencies allowed on "develop" and "master" branches.
### Releasing
1. From the develop branch, prepare a release (example using an HTTP proxy):
......@@ -31,16 +31,17 @@ Note that you must use Java 8 to run Maven when building the project.
$ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 jgitflow:release-start
</code></pre>
1. Update the CHANGELOG according to keepachangelog.com.
1. To perform the release (example using an HTTP proxy):
<pre><code>
2. To perform the release (example using an HTTP proxy):
<pre><code>
$ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 jgitflow:release-finish
</code></pre>
</code></pre>
If, after deployment, the command does not succeed because of some issue with the branches. Fix the issue, then re-run the same command but with 'noDeploy' option set to true to avoid re-deployment:
<pre><code>
<pre><code>
$ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=80 -DnoDeploy=true jgitflow:release-finish
</code></pre>
1. Connect and log in to the OSS Nexus Repository Manager: https://oss.sonatype.org/
1. Go to Staging Profiles and select the pending repository authzforce-*... you just uploaded with `jgitflow:release-finish`
1. Click the Release button to release to Maven Central.
More info on jgitflow: http://jgitflow.bitbucket.org/
</code></pre>
More info on jgitflow: http://jgitflow.bitbucket.org/
3. Connect and log in to the OSS Nexus Repository Manager: https://oss.sonatype.org/
4. Go to Staging Profiles and select the pending repository authzforce-*... you just uploaded with `jgitflow:release-finish`
5. Click the Release button to release to Maven Central.
6. Create a new Release on GitHub (copy-paste the description from previous releases and update the versions)
7. If the [PDP configuration XSD](pdp-engine/src/main/resources/pdp.xsd) has changed with the new release, publish the new schema document in HTML form on https://authzforce.github.io (example for XSD version 8.1) by following the instructions here: https://github.com/authzforce/authzforce.github.io#generating-documentation-for-pdp-configuration-xsd .
......@@ -28,7 +28,9 @@ AuthzForce Core may be used in the following ways:
* [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) (`urn:oasis:names:tc:xacml:3.0:profile:multiple:combined-decision`).
*For further details on what is actually supported regarding the XACML specifications, please refer to the conformance tests [README](pdp-testutils/src/test/resources/conformance/xacml-3.0-from-2.0-ct/README.md).*
* [GeoXACML](http://portal.opengeospatial.org/files/?artifact_id=42734) (Open Geospatial Consortium) support: see [this AuthzForce extension from SecureDimensions](https://github.com/securedimensions/authzforce-geoxacml-basic).
* Enhancements to the XACML standard:
* [GeoXACML](http://portal.opengeospatial.org/files/?artifact_id=42734) (Open Geospatial Consortium) support: see [this AuthzForce extension from SecureDimensions](https://github.com/securedimensions/authzforce-geoxacml-basic).
* Support `<VariableReference>` (indirectly) in `<Target>`/`<Match>` elements: this feature is a workaround for a limitation in XACML schema which does not allow Variables (`<VariableReference>`) in `Match` elements; i.e. the feature allows policy writers to use an equivalent of `<VariableReference>`s in `<Match>` elements (without changing the XACML schema) through a special kind of `<AttributeDesignator>` (specific `Category`, and `AttributeId` is used as `VariableId`). More details in the Usage section below.
* Interfaces:
* Java API: basically a library for instantiating and using a PDP engine from your Java (or any Java-compatible) code;
* CLI (Command-Line Interface): basically an executable that you can run from the command-line to test the engine;
......@@ -224,6 +226,26 @@ Our PDP implementation uses SLF4J for logging, so you can use any SLF4J implemen
For an example of using an AuthzForce PDP engine in a real-life use case, please refer to the JUnit test class [EmbeddedPdpBasedAuthzInterceptorTest](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptorTest.java) and the Apache CXF authorization interceptor [EmbeddedPdpBasedAuthzInterceptor](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptor.java). The test class runs a test similar to @coheigea's [XACML 3.0 Authorization Interceptor test](https://github.com/coheigea/testcases/blob/master/apache/cxf/cxf-sts-xacml/src/test/java/org/apache/coheigea/cxf/sts/xacml/authorization/xacml3/XACML3AuthorizationTest.java) but using AuthzForce as PDP engine instead of OpenAZ. In this test, a web service client requests an Apache-CXF-based web service with a SAML token as credentials (previously issued by a Security Token Service upon successful client authentication) that contains the user ID and roles. Each request is intercepted on the web service side by a [EmbeddedPdpBasedAuthzInterceptor](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptor.java) that plays the role of PEP (Policy Enforcement Point in XACML jargon), i.e. it extracts the various authorization attributes (user ID and roles, web service name, operation...) and requests a decision from a local PDP with these attributes, then enforces the PDP's decision, i.e. forwards the request to the web service implementation if the decision is Permit, else rejects it.
For more information, see the Javadoc of [EmbeddedPdpBasedAuthzInterceptorTest](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptorTest.java).
### Providing current-dateTime, current-date and current-time attributes
By default, the PDP provides the standard environment attributes specified in XACML 3.0 Core specification §10.2.5 (current-time, current-date and current-dateTime) only if they are not provided in the request (from the PEP). This behavior is compliant with XACML 3.0 standard which says (§10.2.5):
>If
values for these
attributes are not present in
the decision request,
then their
values MUST be supplied
by the
context
handler.
Note that it does **not** say *if and only if*, therefore it is also possible and XACML-compliant to make the PDP use its own current-* values (current-time, etc.) all the time, regardless of the request values. This option is referred to as the *override mode*, and it is particularly useful when you do not trust the PEPs (requesters) to provide their own current date/time. You can enable this override mode by configuring an `attributeProvider` of type `StdEnvAttributeProviderDescriptor` with `<override>true</override>` in the PDP configuration, as you can see in [this example (link)](pdp-testutils/src/test/resources/custom/StdEnvAttributeProvider.PDP_ONLY/pdp.xml). More information in the [PDP configuration schema](pdp-engine/src/main/resources/pdp.xsd) ( [HTML form - select the *tns:pdp* element](https://authzforce.github.io/pdp.xsd/8.1) ).
### Using Variables (VariableReference) in Target/Match
In XACML policies (Policy or PolicySet), as defined by the XACML schema, a `<Match>` may only include an `AttributeValue` and an `AttributeDesignator` or `AttributeSelector`; `VariableReference`s are not allowed, which makes it a limitation when you want to match a Variable (from a `VariableDefinition`) in a `Target`. AuthzForce provides a XACML-compliant workaround for this, which consists in enabling a `XacmlVariableBasedAttributeProvider` with a defined Category (see the [PDP configuration XSD](pdp-engine/src/main/resources/pdp.xsd) ( [HTML form - select the *tns:pdp* element](https://authzforce.github.io/pdp.xsd/8.1) for the default Category). As a result, any `<AttributeDesignator>` in that Category is handled like a `VariableReference`, with the `AttributeId` used as `VariableId`.
The configuration of the `XacmlVariableBasedAttributeProvider` in the PDP is shown in [this example (link)](pdp-testutils/src/test/resources/custom/XacmlVarBasedAttributeProvider/pdp.xml) (`attributeProvider` of type `XacmlVarBasedAttributeProviderDescriptor`), applied to some Category `urn:ow2:authzforce:attribute-category:vars`. Then in the [this policy sample (link)](pdp-testutils/src/test/resources/custom/XacmlVarBasedAttributeProvider/policies/policy.xml), you can see an `<AttributeDesignator Category="urn:ow2:authzforce:attribute-category:vars" AttributeId="var1" .../>` which will be handled like `<VariableReference VariableId="var1"/>`.
## Extensions
Experimental features (see [Features](#Features) section) are provided as extensions. If you want to use them, you need to use this Maven dependency (which depends on the `authzforce-ce-core-pdp-engine` already) instead:
* groupId: `org.ow2.authzforce`;
......
......@@ -1033,7 +1033,7 @@
<p>
Provides the standard environment attributes specified
in XACML 3.0 Core specification, §10.2.5: current-time, current-date and current-dateTime.
By default, the PDP engine does not set these attributes on its own and only takes the ones from the request. Therefore, you need to enable this AttributeProvider for strict compliance with XACML 3.0 standard (§10.2.5): <i>If
By default, the PDP engine does not set these attributes on its own and only takes the ones from the request. This AttributeProvider is enabled with <i>override='false'</i> whenever <i>standardAttributeProvidersEnabled='true'</i>, ensuring strict compliance with XACML 3.0 standard (§10.2.5): <i>If
values for these
attributes are not present in
the decision request,
......
Supports Markdown
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