README.md 23.3 KB
Newer Older
1
[![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)
2
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/389/badge)](https://bestpractices.coreinfrastructure.org/projects/389)
Cyril Dangerville's avatar
Cyril Dangerville committed
3
[![Build Status](https://travis-ci.org/authzforce/core.svg?branch=develop)](https://travis-ci.org/authzforce/core)
Cyril Dangerville's avatar
Cyril Dangerville committed
4

Cyril Dangerville's avatar
Cyril Dangerville committed
5
Javadocs: PDP engine [![Javadocs](http://javadoc.io/badge/org.ow2.authzforce/authzforce-ce-core-pdp-engine.svg)](http://javadoc.io/doc/org.ow2.authzforce/authzforce-ce-core-pdp-engine), XACML/JSON extension [![Javadocs](http://javadoc.io/badge/org.ow2.authzforce/authzforce-ce-core-pdp-io-xacml-json.svg)](http://javadoc.io/doc/org.ow2.authzforce/authzforce-ce-core-pdp-io-xacml-json), Test utilities [![Javadocs](http://javadoc.io/badge/org.ow2.authzforce/authzforce-ce-core-pdp-testutils.svg)](http://javadoc.io/doc/org.ow2.authzforce/authzforce-ce-core-pdp-testutils)
6

cdanger's avatar
cdanger committed
7
# AuthzForce Core (Community Edition) 
cdanger's avatar
cdanger committed
8
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).
9

cdanger's avatar
cdanger committed
10
11
12
AuthzForce Core may be used in the following ways:
- Java API: you may use AuthzForce Core from your Java code to instantiate an embedded Java PDP. 
- CLI (Command-Line Interface): you may call AuthzForce Core PDP engine from the command-line (e.g. in a script) by running the provided executable.
13

cdanger's avatar
cdanger committed
14
*HTTP/REST API: if you are interested in using a HTTP/REST API compliant with [REST Profile of XACML 3.0](http://docs.oasis-open.org/xacml/xacml-rest/v1.0/xacml-rest-v1.0.html), check the [AuthzForce RESTful PDP project](http://github.com/authzforce/restful-pdp) and [AuthzForce server project](http://github.com/authzforce/server).*
Cyril Dangerville's avatar
Cyril Dangerville committed
15

cdanger's avatar
cdanger committed
16
17
## Features
* Compliance with the following OASIS XACML 3.0 standards:
cdanger's avatar
cdanger committed
18
19
20
  * [XACML v3.0 - Core standard](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html) 
  * [XACML v3.0 - Core and Hierarchical Role Based Access Control (RBAC) Profile Version 1.0](http://docs.oasis-open.org/xacml/3.0/rbac/v1.0/xacml-3.0-rbac-v1.0.html)
  * [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)  (`urn:oasis:names:tc:xacml:3.0:profile:multiple:repeated-attribute-categories`).
21
22
23
  * [XACML v3.0 - JSON Profile Version 1.0](http://docs.oasis-open.org/xacml/xacml-json-http/v1.0/xacml-json-http-v1.0.html), with extra security features:
      * JSON schema [Draft v6](https://tools.ietf.org/html/draft-wright-json-schema-01) validation;
      * DoS mitigation: JSON parser variant checking max JSON string size, max number of JSON keys/array items and max JSON object depth.
cdanger's avatar
cdanger committed
24
  * Experimental support for:
cdanger's avatar
cdanger committed
25
26
27
    * [XACML v3.0 - Data Loss Prevention / Network Access Control (DLP/NAC) Profile Version 1.0](http://docs.oasis-open.org/xacml/xacml-3.0-dlp-nac/v1.0/xacml-3.0-dlp-nac-v1.0.html): only `dnsName-value` datatype and `dnsName-value-equal` function are supported;
    * [XACML v3.0 - Additional Combining Algorithms Profile Version 1.0](http://docs.oasis-open.org/xacml/xacml-3.0-combalgs/v1.0/xacml-3.0-combalgs-v1.0.html): `on-permit-apply-second` policy combining algorithm;
    * [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`). 
cdanger's avatar
cdanger committed
28

Cyril Dangerville's avatar
Cyril Dangerville committed
29
  *For further details on what is actually supported with regards to 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).*
cdanger's avatar
cdanger committed
30
31
* Interfaces: 
  * Java API: basically a library for instantiating and using a PDP engine from your Java (or any Java-compatible) code;
cdanger's avatar
cdanger committed
32
  * CLI (Command-Line Interface): basically an executable that you can run from the command-line to test the engine;
cdanger's avatar
cdanger committed
33
  
cdanger's avatar
cdanger committed
34
  *HTTP/REST API compliant with [REST Profile of XACML 3.0](http://docs.oasis-open.org/xacml/xacml-rest/v1.0/xacml-rest-v1.0.html) is provided by [AuthzForce RESTful PDP project](http://github.com/authzforce/restful-pdp) for PDP only, and [AuthzForce server project](http://github.com/authzforce/server) for PDP and PAP with multi-tenancy.*
cdanger's avatar
cdanger committed
35
* Safety/Security:
cdanger's avatar
cdanger committed
36
  * Prevention of circular XACML policy references (PolicyIdReference/PolicySetIdReference) as mandated by [XACML 3.0](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html#_Toc325047192);
cdanger's avatar
cdanger committed
37
  * Control of the **maximum XACML PolicyIdReference/PolicySetIdReference depth**;
cdanger's avatar
cdanger committed
38
  * Prevention of circular XACML variable references (VariableReference) as mandated by [XACML 3.0](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html#_Toc325047185); 
cdanger's avatar
cdanger committed
39
  * Control of the **maximum XACML VariableReference depth**;
cdanger's avatar
cdanger committed
40
41
42
43
44
45
* Optional **strict multivalued attribute parsing**: if enabled, multivalued attributes must be formed by grouping all `AttributeValue` elements in the same Attribute element (instead of duplicate Attribute elements); this does not fully comply with [XACML 3.0 Core specification of Multivalued attributes (§7.3.3)](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html#_Toc325047176), but it usually performs better than the default mode since it simplifies the parsing of attribute values in the request.
* Optional **strict attribute Issuer matching**: if enabled, `AttributeDesignators` without Issuer only match request Attributes without Issuer (and same AttributeId, Category...); this option is not fully compliant with XACML 3.0, §5.29, in the case that the Issuer is indeed not present on a AttributeDesignator; but it is the recommended option when all AttributeDesignators have an Issuer (the XACML 3.0 specification (5.29) says: *If the Issuer is not present in the attribute designator, then the matching of the attribute to the named attribute SHALL be governed by AttributeId and DataType attributes alone.*);
* Extensibility points:
  * **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;
Cyril Dangerville's avatar
Cyril Dangerville committed
46
  * **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; 
cdanger's avatar
cdanger committed
47
48
  * **Request Preprocessor**: you may customize the processing of XACML Requests before evaluation by the PDP core engine, e.g. used for supporting new XACML Request formats, and/or 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 Postprocessor**: you may customize the processing of XACML Results after evaluation by the PDP engine, e.g. used for supporting new XACML Response formats, and/or 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);
cdanger's avatar
cdanger committed
49
  * **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);
cdanger's avatar
cdanger committed
50
  * **Policy-by-reference Provider**: you may plug custom policy providers into the PDP engine to allow it to resolve `PolicyIdReference` or `PolicySetIdReference`;
cdanger's avatar
cdanger committed
51
  * **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;
Cyril Dangerville's avatar
Cyril Dangerville committed
52
  * Java extension mechanism to switch HashMap/HashSet implementations (e.g. to get different performance results).
cdanger's avatar
cdanger committed
53
* PIP (Policy Information Point): AuthzForce provides XACML PIP features in the form of extensions called *Attribute Providers*. More information in the previous list of *Extensibility points*.
cdanger's avatar
cdanger committed
54
55
56
57
58
59
60


## Limitations
The following optional features from [XACML v3.0 Core standard](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html) are not supported:
* Elements `AttributesReferences`, `MultiRequests` and `RequestReference`;
* Functions `urn:oasis:names:tc:xacml:3.0:function:xpath-node-equal`, `urn:oasis:names:tc:xacml:3.0:function:xpath-node-match` and `urn:oasis:names:tc:xacml:3.0:function:access-permitted`;
* [Algorithms planned for future deprecation](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html#_Toc325047257).
cdanger's avatar
cdanger committed
61

cdanger's avatar
cdanger committed
62
63
If you are interested in those, you can ask for [support](#Support).

64
65

## Versions
cdanger's avatar
cdanger committed
66
See the [change log](CHANGELOG.md) following the *Keep a CHANGELOG* [conventions](http://keepachangelog.com/).
67
68

## License
Cyril Dangerville's avatar
Cyril Dangerville committed
69
See the [license file](LICENSE).
70

cdanger's avatar
cdanger committed
71
72

## System requirements
cdanger's avatar
cdanger committed
73
74
75
Java (JRE) 8 or later. 

**Make sure** the value - comma-separated list - of the system property `javax.xml.accessExternalSchema` is set to include `http`, to work around Java 8+ external schema access restriction, e.g. with a JVM argument:
cdanger's avatar
cdanger committed
76
77
78
`-Djavax.xml.accessExternalSchema=http`


Cyril Dangerville's avatar
Cyril Dangerville committed
79
80
## Usage
### Getting started
cdanger's avatar
cdanger committed
81
#### CLI
82
Get the [latest executable jar from Maven Central](http://central.maven.org/maven2/org/ow2/authzforce/authzforce-ce-core-pdp-cli/) with groupId/artifactId = `org.ow2.authzforce`/`authzforce-ce-core-pdp-cli` and make sure you are allowed to run it (it is a fully executable JAR), e.g. with command:
cdanger's avatar
cdanger committed
83
84

```
Cyril Dangerville's avatar
Cyril Dangerville committed
85
$ chmod a+x authzforce-ce-core-pdp-cli-13.0.0.jar
cdanger's avatar
cdanger committed
86
```
cdanger's avatar
cdanger committed
87
88

Copy the content of [that folder](pdp-cli/src/test/resources/conformance/xacml-3.0-core/mandatory) to the same directory, and run the executable as follows:
cdanger's avatar
cdanger committed
89

cdanger's avatar
cdanger committed
90
```
Cyril Dangerville's avatar
Cyril Dangerville committed
91
$ ./authzforce-ce-core-pdp-cli-13.0.0.jar pdp.xml IIA001/Request.xml
cdanger's avatar
cdanger committed
92
```
cdanger's avatar
cdanger committed
93

cdanger's avatar
cdanger committed
94
95
* `pdp.xml`: PDP configuration file, that defines the location(s) of XACML policy(ies), among other PDP engine parameters; the content of this file is a XML document compliant with the PDP configuration [XML schema](pdp-engine/src/main/resources/pdp.xsd), so you can read the documentation of every configuration parameter in that schema file;
* `Request.xml`: XACML request in XACML 3.0/XML (core specification) format.
cdanger's avatar
cdanger committed
96
97
98

If you want to test the JSON Profile of XACML 3.0, run it with extra option `-t XACML_JSON`:
```
Cyril Dangerville's avatar
Cyril Dangerville committed
99
$ ./authzforce-ce-core-pdp-cli-13.0.0.jar -t XACML_JSON pdp.xml IIA001/Request.json
cdanger's avatar
cdanger committed
100
```
cdanger's avatar
cdanger committed
101
* `Request.json`: XACML request in XACML 3.0/JSON (Profile) format.
cdanger's avatar
cdanger committed
102
103
104
105

For more info, run it without parameters and you'll get detailed information on usage.

#### Java API
cdanger's avatar
cdanger committed
106
You can either build AuthzForce PDP library from the source code after cloning this git repository, or use the latest release from Maven Central with this information:
107
* groupId: `org.ow2.authzforce`;
Cyril Dangerville's avatar
Cyril Dangerville committed
108
* artifactId: `authzforce-ce-core-pdp-engine`;
109
* packaging: `jar`.
cdanger's avatar
cdanger committed
110

cdanger's avatar
cdanger committed
111
Since this is a Maven artifact and it requires dependencies, you should build your application with a build tool that understands Maven dependencies (e.g. Maven or Gradle), and configure this artifact as a Maven dependency, for instance with Maven in the `pom.xml`:
cdanger's avatar
cdanger committed
112
113
114
115
116
117

```xml
...
      <dependency>
         <groupId>org.ow2.authzforce</groupId>
         <artifactId>authzforce-ce-core-pdp-engine</artifactId>
Cyril Dangerville's avatar
Cyril Dangerville committed
118
         <version>13.0.0</version>
cdanger's avatar
cdanger committed
119
120
121
122
      </dependency>
...

```
123

cdanger's avatar
cdanger committed
124
To get started using a PDP to evaluate XACML requests, the first step is to write/get a XACML 3.0 policy. Please refer to [XACML v3.0 - Core standard](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html) for the syntax. For a basic example, see [this one](pdp-testutils/src/test/resources/conformance/xacml-3.0-from-2.0-ct/mandatory/IIA001/IIA001Policy.xml). 
125

cdanger's avatar
cdanger committed
126
Then instantiate a PDP engine configuration with method [PdpEngineConfiguration#getInstance(String)](pdp-engine/src/main/java/org/ow2/authzforce/core/pdp/impl/PdpEngineConfiguration.java#L663). The required parameter *confLocation* must be the location of the PDP configuration file. The content of such file is a XML document compliant with the PDP configuration [XML schema](pdp-engine/src/main/resources/pdp.xsd). This schema defines every configuration parameter with associated documentation. Here is a minimal example of configuration:
127

Cyril Dangerville's avatar
Cyril Dangerville committed
128
129
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
cdanger's avatar
cdanger committed
130
   <pdp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://authzforce.github.io/core/xmlns/pdp/6.0" version="6.0.0">
Cyril Dangerville's avatar
Cyril Dangerville committed
131
132
133
	   <rootPolicyProvider id="rootPolicyProvider" xsi:type="StaticRootPolicyProvider" policyLocation="${PARENT_DIR}/policy.xml" />
   </pdp>
   ```
cdanger's avatar
cdanger committed
134
   This is a basic PDP configuration with basic settings and the root policy (XACML 3.0 Policy document) loaded from a file `policy.xml` located in the same directory as this PDP configuration file (see previous paragraph for an example of policy).
Cyril Dangerville's avatar
Cyril Dangerville committed
135

cdanger's avatar
cdanger committed
136
As a result of calling method `getInstance(...)`, you get a `PdpEngineConfiguration` object. Basic example of Java code using a PDP configuration file in some folder `/opt/authzforce`:
cdanger's avatar
cdanger committed
137
138

```java
cdanger's avatar
cdanger committed
139
final PdpEngineConfiguration pdpEngineConf = PdpEngineConfiguration.getInstance("file:///opt/authzforce/pdp.xml"); 
cdanger's avatar
cdanger committed
140
141
142
```

Then the next step depends on the kind of decision request you want to evaluate. The various alternatives are detailed in the next sections.
143

144
##### Evaluating Requests in AuthzForce native API (most efficient)
cdanger's avatar
cdanger committed
145
If you are creating decision requests internally, i.e. directly from your Java code (not from any data serialization format), you'd better use AuthzForce native interface.
cdanger's avatar
cdanger committed
146
147
148
149
150
151
152
You can pass the `PdpEngineConfiguration` to `BasePdpEngine(PdpEngineConfiguration)` constructor in order to instantiate a PDP engine. With this, you can evaluate a decision request (more precisely an equivalent of a Individual Decision Request as defined by the XACML Multiple Decision Profile) in AuthzForce's native model by calling `evaluate(DecisionRequest)` or (multiple decision requests with `evaluate(List)`). In order to build a `DecisionRequest`, you may use the request builder returned by `BasePdpEngine#newRequestBuilder(...)`. 

Basic example of Java code (based on previous line of code):

```java
...
/*
cdanger's avatar
cdanger committed
153
 * Create the PDP engine. You can reuse the same for all requests, so do it only once for all.
cdanger's avatar
cdanger committed
154
155
156
157
158
 */
final BasePdpEngine pdp = new BasePdpEngine(pdpEngineConf);
...

// Create the XACML request in native model
cdanger's avatar
cdanger committed
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
final DecisionRequestBuilder<?> requestBuilder = pdp.newRequestBuilder(-1, -1);
/*
 * If you care about memory optimization (avoid useless memory allocation), make sure you know the (expected) number of XACML attribute categories and (expected) total number of attributes in the request, and use these as arguments to newRequestBuilder(int,int) method, instead of negative values like above.
 * e.g. 3 attribute categories, 4 total attributes in this case
 */
// final DecisionRequestBuilder<?> requestBuilder = pdp.newRequestBuilder(3, 4);

// Add subject ID attribute (access-subject category), no issuer, string value "john"
final AttributeFqn subjectIdAttributeId = AttributeFqns.newInstance(XACML_1_0_ACCESS_SUBJECT.value(), Optional.empty(), XacmlAttributeId.XACML_1_0_SUBJECT_ID.value());
final AttributeBag<?> subjectIdAttributeValues = Bags.singletonAttributeBag(StandardDatatypes.STRING, new StringValue("john"));
requestBuilder.putNamedAttributeIfAbsent(subjectIdAttributeId, subjectIdAttributeValues);

// Add subject role(s) attribute to access-subject category, no issuer, string value "boss"
final AttributeFqn subjectRoleAttributeId = AttributeFqns.newInstance(XACML_1_0_ACCESS_SUBJECT.value(), Optional.empty(), XacmlAttributeId.XACML_2_0_SUBJECT_ROLE.value());
final AttributeBag<?> roleAttributeValues = Bags.singletonAttributeBag(StandardDatatypes.STRING, new StringValue("boss"));
requestBuilder.putNamedAttributeIfAbsent(subjectRoleAttributeId, roleAttributeValues);

// Add resource ID attribute (resource category), no issuer, string value "/some/resource/location"
final AttributeFqn resourceIdAttributeId = AttributeFqns.newInstance(XACML_3_0_RESOURCE.value(), Optional.empty(), XacmlAttributeId.XACML_1_0_RESOURCE_ID.value());
final AttributeBag<?> resourceIdAttributeValues = Bags.singletonAttributeBag(StandardDatatypes.STRING, new StringValue("/some/resource/location"));
requestBuilder.putNamedAttributeIfAbsent(resourceIdAttributeId, resourceIdAttributeValues);

// Add action ID attribute (action category), no issuer, string value "GET"
final AttributeFqn actionIdAttributeId = AttributeFqns.newInstance(XACML_3_0_ACTION.value(), Optional.empty(), XacmlAttributeId.XACML_1_0_ACTION_ID.value());
final AttributeBag<?> actionIdAttributeValues = Bags.singletonAttributeBag(StandardDatatypes.STRING, new StringValue("GET"));
requestBuilder.putNamedAttributeIfAbsent(actionIdAttributeId, actionIdAttributeValues);
cdanger's avatar
cdanger committed
185
186
187
188
189
190
191
192
193
194

// No more attribute, let's finalize the request creation
final DecisionRequest request = requestBuilder.build(false);
// Evaluate the request
final DecisionResult result = pdp.evaluate(request);
if(result.getDecision() == DecisionType.PERMIT) {
	// This is a Permit :-)
	...
} else {
	// Not a Permit :-( (maybe Deny, NotApplicable or Indeterminate)
cdanger's avatar
cdanger committed
195
	...
cdanger's avatar
cdanger committed
196
197
198
199
200
}
```

See [EmbeddedPdpBasedAuthzInterceptor#createRequest(...) method](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptor.java#L158) for a more detailed example. Please look at the Javadoc for the full details.

201

cdanger's avatar
cdanger committed
202
203
204
205
206
##### Evaluating Requests in XACML/XML format
You can pass the `PdpEngineConfiguration` to `PdpEngineAdapters#newXacmlJaxbInoutAdapter(PdpEngineConfiguration)` utility method to instantiate a PDP supporting XACML 3.0/XML (core specification) format. You can evaluate such XACML Request by calling the `evaluate(...)` methods.

##### Evaluating Requests in XACML/JSON format
To instantiate a PDP supporting XACML 3.0/JSON (JSON Profile) format, you may reuse the test code from [PdpEngineXacmlJsonAdapters](pdp-io-xacml-json/src/test/java/org/ow2/authzforce/core/pdp/io/xacml/json/test/PdpEngineXacmlJsonAdapters.java).
207
208
209
210
You will need an extra dependency as well, available from Maven Central:
* groupId: `org.ow2.authzforce`;
* artifactId: `authzforce-ce-core-pdp-io-xacml-json`;
* packaging: `jar`.
cdanger's avatar
cdanger committed
211
212
213
214

##### Logging
Our PDP implementation uses SLF4J for logging so you can use any SLF4J implementation to manage logging. The CLI executable includes logback implementation, so you can use logback configuration file, e.g. [logback.xml](pdp-testutils/src/test/resources/logback.xml), for configuring loggers, appenders, etc.

cdanger's avatar
cdanger committed
215

Cyril Dangerville's avatar
Cyril Dangerville committed
216
### Example of usage in a web service PEP
cdanger's avatar
cdanger committed
217
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 a 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.
Cyril Dangerville's avatar
Cyril Dangerville committed
218
For more information, see the Javadoc of  [EmbeddedPdpBasedAuthzInterceptorTest](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/pep/cxf/EmbeddedPdpBasedAuthzInterceptorTest.java).
219

Cyril Dangerville's avatar
Cyril Dangerville committed
220
## Extensions
cdanger's avatar
cdanger committed
221
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:
cdanger's avatar
cdanger committed
222
223
224
225
226
227
228
229
230
231
* groupId: `org.ow2.authzforce`;
* artifactId: `authzforce-ce-core-pdp-testutils`;
* packaging: `jar`

If you are still missing features in AuthzForce, you can make your own extensions/plugins (without changing the existing code), as described on the [wiki](../../wiki/Extensions).

If you are using the Java API with extensions configured by XML (Policy Providers, Attribute Providers...), you must use `PdpEngineConfiguration#getInstance(String, String, String)` to instantiate the PDP engine, instead of `PdpEngineConfiguration#getInstance(String)` mentioned previously. The two last extra parameters are mandatory in this case:
1. *catalogLocation*: location of the XML catalog: 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](pdp-engine/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: 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](pdp-testutils/src/test/resources/pdp-ext.xsd) in the sources as an example.

232

cdanger's avatar
cdanger committed
233
234
## Support

235
You should use [AuthzForce users' mailing list](https://mail.ow2.org/wws/arc/authzforce-users/) as first contact for any communication about AuthzForce: question, feature request, notification, potential issue (unconfirmed), etc.
Cyril Dangerville's avatar
Cyril Dangerville committed
236
237

If you are experiencing any bug with this project and you indeed confirm this is not an issue with your environment (contact the users mailing list first if you are unsure), please report it on the [OW2 Issue Tracker](https://jira.ow2.org/browse/AUTHZFORCE/).
cdanger's avatar
cdanger committed
238
Please include as much information as possible; the more we know, the better the chance of a quicker resolution:
cdanger's avatar
cdanger committed
239

cdanger's avatar
cdanger committed
240
* Software version
cdanger's avatar
cdanger committed
241
* Platform (OS and JRE)
Cyril Dangerville's avatar
Cyril Dangerville committed
242
* 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.
cdanger's avatar
cdanger committed
243
244
* Log output can be useful too; sometimes enabling DEBUG logging can help;
* Your code & configuration files are often useful.
cdanger's avatar
cdanger committed
245

Cyril Dangerville's avatar
Cyril Dangerville committed
246
## Security - Vulnerability reporting
247
248
If you want to report a vulnerability, you must do so on the [OW2 Issue Tracker](https://jira.ow2.org/browse/AUTHZFORCE/) with *Security Level* set to **Private**. Then, if the AuthzForce team can confirm it, they will change it to **Public** and set a fix version.

Cyril Dangerville's avatar
Cyril Dangerville committed
249
250
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).