README.md 33.8 KB
Newer Older
Cyril Dangerville's avatar
Cyril Dangerville committed
1
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/9c9812d7b09549e59edb99f3948bca4a)](https://www.codacy.com/gh/authzforce/core/dashboard?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)
3
[![Build Status](https://github.com/authzforce/core/actions/workflows/maven.yml/badge.svg?branch=develop)](https://github.com/authzforce/core/actions/workflows/maven.yml)
fossabot's avatar
fossabot committed
4
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fauthzforce%2Fcore.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fauthzforce%2Fcore?ref=badge_shield)
Cyril Dangerville's avatar
Cyril Dangerville committed
5

Cyril Dangerville's avatar
Cyril Dangerville committed
6
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)
7

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

cdanger's avatar
cdanger committed
11
12
13
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.
14

15
***HTTP/REST server**: if you are interested in using an 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
16

cdanger's avatar
cdanger committed
17
18
## Features
* Compliance with the following OASIS XACML 3.0 standards:
cdanger's avatar
cdanger committed
19
20
21
  * [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`).
22
23
24
  * [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
25
  * Experimental support for:
cdanger's avatar
cdanger committed
26
27
28
    * [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
29

30
  *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).*
cdanger's avatar
cdanger committed
31
32
33
* 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. 
cdanger's avatar
cdanger committed
34
35
* 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
36
  * CLI (Command-Line Interface): basically an executable that you can run from the command-line to test the engine;
cdanger's avatar
cdanger committed
37
  
cdanger's avatar
cdanger committed
38
  *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
39
* Safety & Security:
cdanger's avatar
cdanger committed
40
  * 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
41
  * Control of the **maximum XACML PolicyIdReference/PolicySetIdReference depth**;
cdanger's avatar
cdanger committed
42
  * 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
43
  * Control of the **maximum XACML VariableReference depth**;
cdanger's avatar
cdanger committed
44
45
46
* Performance:
  * 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 for better performance 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.*);
Cyril Dangerville's avatar
Cyril Dangerville committed
47
  * **Optimal integer data-type** implementation: the `maxIntegerValue` configuration parameter (expected maximum absolute value in XACML attributes of type `http://www.w3.org/2001/XMLSchema#integer`) helps the PDP choose the most efficient Java data-type. By default, the XACML/XML type `http://www.w3.org/2001/XMLSchema#integer` is mapped to the larger Java data-type: `BigInteger`. However, this may be overkill for example in the case of integer attributes representing the age of a person; in this case, the `Short` type is more appropriate and especially more efficient. Therefore, decreasing the `maxIntegerValue` value as much as possible, based on the range you expect your integer values to fit in, makes the PDP engine more efficient on integer handling: lower memory consumption, faster computations.
48
  * **Pluggable Decision Cache**: you can plug in your own XACML Decision Cache mechanism to speed up evaluation of (repetitive) requests. See down below for more info (Decision Cache extension).
cdanger's avatar
cdanger committed
49
* Extensibility points:
50
51
52
53
54
55
  * **[Attribute Datatypes](https://github.com/authzforce/core/wiki/XACML-Data-Types)**: you may extend the PDP engine with custom XACML attribute datatypes;
  * **[Functions](https://github.com/authzforce/core/wiki/XACML-Functions)**: you may extend the PDP engine with custom XACML functions;
  * **[Combining Algorithms](https://github.com/authzforce/core/wiki/XACML-Combining-Algorithms)**: you may extend the PDP engine with custom XACML policy/rule combining algorithms;
  * **[Attribute Providers a.k.a. PIPs](https://github.com/authzforce/core/wiki/Attribute-Providers)** (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 Preprocessor](https://github.com/authzforce/core/wiki/XACML-Request-Preprocessors)**: 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](https://github.com/authzforce/core/wiki/XACML-Result-Postprocessors)**: 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);
56
  * **[Policy Provider](https://github.com/authzforce/core/wiki/Policy-Providers)**: you may plug custom policy providers into the PDP engine to allow it to resolve `PolicyIdReference` or `PolicySetIdReference`;
cdanger's avatar
cdanger committed
57
  * **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;
58
  * Java [extension mechanism to switch HashMap/HashSet implementations](https://github.com/authzforce/core/wiki/Hashed-Collections) (e.g. to get different performance results).
cdanger's avatar
cdanger committed
59
* 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
60
61
62


## Limitations
63
64

### XACML 2.0 support and migrating to XACML 3.0
Cyril Dangerville's avatar
Cyril Dangerville committed
65
As mentioned in the Features section, we do not support XACML 2.0 but only XACML 3.0, and we strongly recommend you migrate to XACML 3.0 as XACML 2.0 has become obsolete. In order to help you in the migration from XACML 2.0 to 3.0, we provide a way to migrate all your XACML 2.0 policies to XACML 3.0 automatically by applying the XSLT stylesheets in the [migration folder](migration). First download the stylesheets `xacml2To3Policy.xsl` and `xacml3-policy-c14n.xsl` from that folder, then apply them to your XACML 2.0 policy files using any XSLT engine supporting XSLT 2.0. For example, using [SAXON-HE 9.x or later](https://www.saxonica.com/download/java.xml), you may do it as follows:
66
67
68
69
70
71
72
73

```shell
$ XACML_20_POLICY_FILE="policy.xml"
$  java -jar /path/to/Saxon-HE-10.3.jar -xsl:xacml2To3Policy.xsl -s:$XACML_20_POLICY_FILE -o:/tmp/${XACML_20_POLICY_FILE}.new
$  java -jar /path/to/Saxon-HE-10.3.jar -xsl:xacml3-policy-c14n.xsl -s:/tmp/${XACML_20_POLICY_FILE}.new -o:$XACML_20_POLICY_FILE.new
```

### Optional XACML 3.0 features
cdanger's avatar
cdanger committed
74
75
76
77
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
78

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

81
82

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

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

fossabot's avatar
fossabot committed
88
89
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fauthzforce%2Fcore.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fauthzforce%2Fcore?ref=badge_large)

cdanger's avatar
cdanger committed
90
## System requirements
91
Java (JRE) version: 11 or later. Java 8 is no longer supported.
cdanger's avatar
cdanger committed
92

Cyril Dangerville's avatar
Cyril Dangerville committed
93
94
## Usage
### Getting started
cdanger's avatar
cdanger committed
95
#### CLI
Cyril Dangerville's avatar
Cyril Dangerville committed
96
Get the latest executable jar from Maven Central by following the `authzforce-ce-core-pdp-cli` link on [the latest release page](https://github.com/authzforce/core/releases/latest), and make sure you are allowed to run it (it is a fully executable JAR), e.g. with command:
cdanger's avatar
cdanger committed
97
98

```
99
$ chmod a+x authzforce-ce-core-pdp-cli-14.0.0.jar
cdanger's avatar
cdanger committed
100
```
cdanger's avatar
cdanger committed
101

cdanger's avatar
cdanger committed
102
To give you an example on how to test a XACML Policy (or PolicySet) and Request, you may copy the content of [that folder](pdp-cli/src/test/resources/conformance/xacml-3.0-core/mandatory) to the same directory as the executable, and run the executable as follows:
cdanger's avatar
cdanger committed
103

cdanger's avatar
cdanger committed
104
```
105
$ ./authzforce-ce-core-pdp-cli-14.0.0.jar pdp.xml IIA001/Request.xml
cdanger's avatar
cdanger committed
106
```
cdanger's avatar
cdanger committed
107

cdanger's avatar
cdanger committed
108
* `pdp.xml`: PDP configuration file in XML format, that defines the location(s) of XACML policy(ies) and more; for more information about PDP configuration parameters, the configuration format is fully specified and documented in the [XML schema `pdp.xsd`](pdp-engine/src/main/resources/pdp.xsd), also available in a [more user-friendly HTML form](https://authzforce.github.io/pdp.xsd/7.1) (start with the `pdp` element as the root element in a PDP configuration). **Feel free to change the policy location to point to your own for testing.**
cdanger's avatar
cdanger committed
109
* `Request.xml`: XACML request in XACML 3.0/XML (core specification) format. **Feel free to replace with your own for testing.**
cdanger's avatar
cdanger committed
110
111
112

If you want to test the JSON Profile of XACML 3.0, run it with extra option `-t XACML_JSON`:
```
113
$ ./authzforce-ce-core-pdp-cli-14.0.0.jar -t XACML_JSON pdp.xml IIA001/Request.json
cdanger's avatar
cdanger committed
114
```
cdanger's avatar
cdanger committed
115
* `Request.json`: XACML request in XACML 3.0/JSON (Profile) format. **Feel free to replace with your own for testing.**
cdanger's avatar
cdanger committed
116

117
For more info, run it without parameters, and you'll get detailed information on usage.
cdanger's avatar
cdanger committed
118

Cyril Dangerville's avatar
Cyril Dangerville committed
119
120
121
122
123
124
For **troubleshooting**, you can increase the log level of the logger(s) in the Logback configuration file `logback.xml` to `INFO` or `DEBUG`, esp. the logger named `org.ow2.authzforce`. Then run the CLI as follows:

```shell
$ java -jar -Dlogback.configurationFile=./logback.xml authzforce-ce-core-pdp-cli-14.0.0.jar pdp.xml IIA001/Request.xml
```

cdanger's avatar
cdanger committed
125
#### Java API
cdanger's avatar
cdanger committed
126
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:
127
* groupId: `org.ow2.authzforce`;
Cyril Dangerville's avatar
Cyril Dangerville committed
128
* artifactId: `authzforce-ce-core-pdp-engine`;
129
* packaging: `jar`.
cdanger's avatar
cdanger committed
130

131
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
132
133
134
135
136
137

```xml
...
      <dependency>
         <groupId>org.ow2.authzforce</groupId>
         <artifactId>authzforce-ce-core-pdp-engine</artifactId>
138
         <version>${latest.version}</version>
cdanger's avatar
cdanger committed
139
140
141
142
      </dependency>
...

```
143

cdanger's avatar
cdanger committed
144
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). 
145

cdanger's avatar
cdanger committed
146
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. For more information about PDP configuration parameters, the configuration format is fully specified and documented in the [XML schema `pdp.xsd`](pdp-engine/src/main/resources/pdp.xsd), also available in a [more user-friendly HTML form](https://authzforce.github.io/pdp.xsd/7.1) (start with the `pdp` element as the root element in a PDP configuration). Here is a minimal example of configuration:
147

Cyril Dangerville's avatar
Cyril Dangerville committed
148
149
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
150
   <pdp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://authzforce.github.io/core/xmlns/pdp/7" version="7.1">
151
152
153
	  <policyProvider id="policyProvider" xsi:type="StaticPolicyProvider">
	    <policyLocation>${PARENT_DIR}/policy.xml</policyLocation>
	  </policyProvider>
Cyril Dangerville's avatar
Cyril Dangerville committed
154
155
   </pdp>
   ```
cdanger's avatar
cdanger committed
156
   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
157

cdanger's avatar
cdanger committed
158
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
159
160

```java
cdanger's avatar
cdanger committed
161
final PdpEngineConfiguration pdpEngineConf = PdpEngineConfiguration.getInstance("file:///opt/authzforce/pdp.xml"); 
cdanger's avatar
cdanger committed
162
163
164
```

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

166
##### Evaluating Requests in AuthzForce native API (most efficient)
cdanger's avatar
cdanger committed
167
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.
168
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 an 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(...)`. 
cdanger's avatar
cdanger committed
169
170
171
172
173
174

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

```java
...
/*
cdanger's avatar
cdanger committed
175
 * Create the PDP engine. You can reuse the same for all requests, so do it only once for all.
cdanger's avatar
cdanger committed
176
177
178
179
180
 */
final BasePdpEngine pdp = new BasePdpEngine(pdpEngineConf);
...

// Create the XACML request in native model
cdanger's avatar
cdanger committed
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
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
207
208
209
210
211
212
213
214
215
216

// 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
217
	...
cdanger's avatar
cdanger committed
218
219
220
221
222
}
```

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.

223

cdanger's avatar
cdanger committed
224
##### Evaluating Requests in XACML/XML format
Cyril Dangerville's avatar
Cyril Dangerville committed
225
You can pass the `PdpEngineConfiguration` to `PdpEngineAdapters#newXacmlJaxbInoutAdapter(PdpEngineConfiguration)` utility method to instantiate a PDP supporting XACML 3.0/XML (core specification) format (`PdpEngineInoutAdapter<Request, Response>`), with which you can evaluate XACML Requests by calling its `evaluate(...)` methods.
cdanger's avatar
cdanger committed
226
227

##### Evaluating Requests in XACML/JSON format
Cyril Dangerville's avatar
Cyril Dangerville committed
228
To instantiate a PDP supporting XACML 3.0/JSON (JSON Profile) format, you may reuse the test code from [PdpEngineXacmlJsonAdapters](pdp-testutils/src/test/java/org/ow2/authzforce/core/pdp/testutil/test/json/PdpEngineXacmlJsonAdapters.java), esp. the method `PdpEngineXacmlJsonAdapters#newXacmlJsonInoutAdapter(PdpEngineConfiguration)` which returns a `PdpEngineInoutAdapter<JSONObject,JSONObject>` on which you can call the `evaluate(...)` method with the JSON request as input.
229

230
231
232
233
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
234

cdanger's avatar
cdanger committed
235
236
237
##### Evaluating Requests in other formats
You can support other non-XACML formats of access requests (resp. responses), including your own, by implementing your own [Request Preprocessor](https://github.com/authzforce/core/wiki/XACML-Request-Preprocessors) (resp. [Result Postprocessor](https://github.com/authzforce/core/wiki/XACML-Result-Postprocessors) ).

cdanger's avatar
cdanger committed
238
##### Logging
239
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
240

cdanger's avatar
cdanger committed
241

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

cdanger's avatar
cdanger committed
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
### 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"/>`.


Cyril Dangerville's avatar
Cyril Dangerville committed
266
## Extensions
cdanger's avatar
cdanger committed
267
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
268
269
270
271
272
273
274
275
276
277
* 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.

278

279
280
281
282
## Integration with other Security Policy models, languages, formats, etc.
### SPIF (Security Policy Information File)
A SPIF (Security Policy Information File) defines a security labeling policy in a XML document (based on the [SPIF XML schema](spif-utils/spif.xsd)). More info on the [Open XML SPIF website](http://www.xmlspif.org/).

Cyril Dangerville's avatar
Cyril Dangerville committed
283
[NATO ADatP-4774.1](https://nso.nato.int/nso/nsdd/main/standards/srd-details/222/EN) - related to [STANAG 4774](https://nso.nato.int/nso/nsdd/main/standards/stanag-details/8612/EN) - gives implementation guidance on how to generate a XACML policy from a SPIF, including an example of XSLT stylesheet. We made a few improvements to that stylesheet, using the latest XACML 3.0 enhancements and AuthzForce optimizations, and differentiating READ and WRITE actions in accordance to the Bell-Lapadula model. The enhanced stylesheet is available in the [spif-utils](spif-utils) folder in two versions:
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298

- `spif2xacml-for-xpath-1.0.xsl`: SPIF-to-XACML policy transformation XSLT using XPath 1.0, more verbose and less efficient than the XPath 2.0 version below, available mostly for historical reasons (no longer maintained except bug fixing).
- `spif2xacml-for-xpath-2.0.xsl`: SPIF-to-XACML policy transformation XSLT using XPath 2.0 features (not available in 1.0), with the option to enable AuthzForce optimizations (XSLT parameter `authzforce_optimized`) for further enhancements. Disable this option if you want strict XACML 3.0 compliance (less optimized).

For example, you may generate the XACML policy from the sample [ACME SPIF](spif-utils/ACME-SPIF-example.xml) (from ADatP-4774.1) using XSLT engine of [SAXON-HE 9.x or later](https://www.saxonica.com/download/java.xml) on the command line as follows

```shell
$ java -jar Saxon-HE-10.3.jar -xsl:spif-utils/spif2xacml-for-xpath-2.0.xsl -s:spif-utils/ACME-SPIF-example.xml -o:/tmp/ACME-XACML-policy.xml
```

Same example but without AuthzForce optimizations:
```shell
$ java -jar Saxon-HE-10.3.jar authzforce_optimized=false -xsl:spif-utils/spif2xacml-for-xpath-2.0.xsl -s:spif-utils/ACME-SPIF-example.xml -o:/tmp/ACME-XACML-policy.xml
```

Cyril Dangerville's avatar
Cyril Dangerville committed
299
300
In both cases, **the generated XACML policy makes use of `AttributeSelectors`**, so make sure your XACML engine supports those. In the case of AuthzForce, you need to set `xPathEnabled="true"` in the PDP configuration (`pdp.xml`) to enable support for `AttributeSelectors`, like in the [XacmlVariableUsedAsXPathVariable test](pdp-testutils/src/test/resources/custom/XacmlVariableUsedAsXPathVariable).

cdanger's avatar
cdanger committed
301
302
## Support

Cyril Dangerville's avatar
Cyril Dangerville committed
303
You should use [AuthzForce users' mailing list](https://mail.ow2.org/wws/info/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
304

305
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://gitlab.ow2.org/authzforce/core/issues).
cdanger's avatar
cdanger committed
306
Please include as much information as possible; the more we know, the better the chance of a quicker resolution:
cdanger's avatar
cdanger committed
307

cdanger's avatar
cdanger committed
308
* Software version
cdanger's avatar
cdanger committed
309
* Platform (OS and JRE)
Cyril Dangerville's avatar
Cyril Dangerville committed
310
* 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
311
312
* Log output can be useful too; sometimes enabling DEBUG logging can help;
* Your code & configuration files are often useful.
cdanger's avatar
cdanger committed
313

Cyril Dangerville's avatar
Cyril Dangerville committed
314
## Security - Vulnerability reporting
315
If you want to report a vulnerability, you must do so on the [OW2 Issue Tracker](https://gitlab.ow2.org/authzforce/core/issues) and **make sure the checkbox** *This issue is confidential and should only be visible to team members with at least Reporter access* **is checked when creating the issue**. Then, if the AuthzForce team can confirm it, they will uncheck it to make the issue public.
316

Cyril Dangerville's avatar
Cyril Dangerville committed
317
## Contributing
318
See [CONTRIBUTING.md](CONTRIBUTING.md).
319
320

## Adoption
Cyril Dangerville's avatar
Cyril Dangerville committed
321
If you are (or have been) using AuthzForce and would be so kind as to mention it [here](ADOPTERS.md), please submit a pull request with your change to [ADOPTERS.md](ADOPTERS.md).