All notable changes to this project are documented in this file following the [Keep a CHANGELOG](http://keepachangelog.com) conventions. We try to apply [Semantic Versioning](http://semver.org) with one particular rule: the version must be equal to or greater than the version of the _authzforce-ce-rest-api-model_ dependency (declared in _rest-service_ module's POM). Indeed, this dependency holds the resources of the REST API specification implemented by this project. Therefore, the rule helps relate a specific version of this project to the specific version of the REST API specification that is implemented/supported.
## 5.2.0
### Added
- REST API spec (authzforce-ce-rest-api-model) v5.1.0 support: enhanced management of PDP features, i.e. all supported features may be listed, and each feature may have a 'type' and an 'enabled' (true or false) state that can be updated via the API
- Supported PDP features by type:
- Type `urn:ow2:authzforce:feature-type:pdp:core` (PDP core engine features, as opposed to extensions below): `urn:ow2:authzforce:feature:pdp:core:xpath-eval` (experimental support for XACML AttributeSelector, xpathExpression datatype and xpath-node-count function), `urn:ow2:authzforce:feature:pdp:core:strict-attribute-issuer-match` (enable strict Attribute Issuer matching, i.e. AttributeDesignators without Issuer only match request Attributes with same AttributeId/Category but without Issuer)
- Type `urn:ow2:authzforce:feature-type:pdp:data-type`: any custom XACML Data type extension
- Type `urn:ow2:authzforce:feature-type:pdp:function`: any custom XACML function extension
- Type `urn:ow2:authzforce:feature-type:pdp:function-set`: any set of custom XACML function extensions
- Type `urn:ow2:authzforce:feature-type:pdp:combining-algorithm`: any custom XACML policy/rule combining algorithm extension
- Type `urn:ow2:authzforce:feature-type:pdp:request-filter`: any custom XACML request filter + native ones, i.e. `urn:ow2:authzforce:xacml:request-filter:default-lax` (default XACML Core-compliant Individual Decision Request filter), `urn:ow2:authzforce:xacml:request-filter:default-strict` (like previous one except duplicate <Attribute> in a <Attributes> is not allowed), `urn:ow2:authzforce:xacml:request-filter:multiple:repeated-attribute-categories-lax` (request filter implenting XACML profile `urn:oasis:names:tc:xacml:3.0:profile:multiple:repeated-attribute-categories`), `urn:ow2:authzforce:xacml:request-filter:multiple:repeated-attribute-categories-strict` (like previous one except duplicate <Attribute> in a <Attributes> is not allowed)
- Type `urn:ow2:authzforce:feature-type:pdp:result-filter`: any custom XACML Result filter extension
- Distribution upgrader now supporting all 4.x versions as old versions
## 5.1.2
### Added
- REST API features (see *Changed* section for API changes):
...
...
@@ -12,9 +27,9 @@ All notable changes to this project are documented in this file following the [K
- Fast Infoset support with new data representation type `application/fastinfoset` (in addition to `application/xml`) for all API payloads. Requires Authzforce Server to be started in a specific mode using [JavaEE Environment Entry](https://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Environment_Entries)`spring.profiles.active` in Tomcat-specific Authzforce webapp context file (`authzforce-ce.xml`). Default type remains `application/xml` (default type is used when a wildcard is received as Accept header value from the client)
- API caches domains' PDPs and externalIds for performance reasons, but it is now possible to force re-synchronizing this domain cache after any change to the backend domain repository, i.e. reloading domains' PDPs and externalIDs without restarting the webapp or server:
-`GET or HEAD /domains` forces re-synchronization of all domains
-`GET or HEAD /domain/{domainId}/properties` forces re-synchronization of externalId with domain properties file (properties.xml) in the domain directory
-`GET or HEAD /domain/{domainId}/pap/pdp.properties`; or `GET or HEAD /domain/{domainId}/pap/policies` forces re-synchronization of PDP with configuration file (`pdp.xml`) and policy files in subfolder `policies` of the domain directory
-`DELETE /domain/{domainId}` forces removal of the domain from cache, and the domain directory if it still exists (removes from cache only if directory already removed)
-`GET or HEAD /domains/{domainId}/properties` forces re-synchronization of externalId with domain properties file (properties.xml) in the domain directory
-`GET or HEAD /domains/{domainId}/pap/pdp.properties`; or `GET or HEAD /domains/{domainId}/pap/policies` forces re-synchronization of PDP with configuration file (`pdp.xml`) and policy files in subfolder `policies` of the domain directory
-`DELETE /domains/{domainId}` forces removal of the domain from cache, and the domain directory if it still exists (removes from cache only if directory already removed)
- Properties for controlling the size of incoming XML (`maxElementDepth`, `maxChildElements`, `maxAttributeCount`, `maxAttributeSize`, `maxTextLength`) corresponding to [CXF XML security properties](http://cxf.apache.org/docs/security.html#Security-XML) may be configured as [JavaEE Environment Entries](https://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Environment_Entries) in Tomcat-specific Authzforce webapp context file (`authzforce-ce.xml`). Only `maxElementDepth` and `maxChildElements` are supported in Fast Infoset mode (due to issue [CXF-6848](https://issues.apache.org/jira/browse/CXF-6848)).
- Completed 100% XACML 3.0 Core Specification compliance with support of Extended Indeterminate values in policy evaluation (XACML 3.0 Core specification, section 7.10-7.14, appendix C: combining algorithms)
- Distribution upgrader: tool to upgrade from Authzforce 4.2.0
...
...
@@ -85,6 +100,7 @@ All notable changes to this project are documented in this file following the [K
- Detection of circular references in Policy(Set)IdReferences or VariableReference
- Configurable max allowed depth of PolicySetIdReference or VariableReference
## 4.2.0
### Added
- Distribution as Debian package
...
...
@@ -93,6 +109,7 @@ All notable changes to this project are documented in this file following the [K
@@ -8,3 +8,6 @@ Server components and distribution of AuthZForce authorization service (FIWARE A
This project also provides the Reference Implementation (GEri) of [FIWARE](https://www.fiware.org)*Authorization PDP* Generic Enabler (GE). More info on the [FIWARE catalogue](http://catalogue.fiware.org/enablers/authorization-pdp-authzforce).
The manuals are available on [readthedocs.org](http://authzforce-ce-fiware.readthedocs.org/).
Note for contributers:
The sources for the manuals are located in [fiware repository](http://github.com/authzforce/fiware/doc).
<!-- Set timestamp property to be used in debian/changelog -->
<plugin>
<!--
Compute timestamp to be used in debian/changes.jdeb.txt
We cannot use Maven property 'maven.build.timestamp.format' because already used to compute 'currentYear' property inherited from authzforce-ce-parent, with a different format, so we use a plugin.
This guide provides the procedure to install the AuthZForce server from the `tar.gz` distribution, including system requirements and troubleshooting instructions.
This guide provides the procedure to install the AuthZForce server from the tarball distribution, including system requirements and troubleshooting instructions.
## System Requirements
* CPU frequency: 2.6 GHz min
* CPU architecture: i686/x86_64
* RAM: 4GB min
* Disk space: 10 GB min
* File system: ext4
* Operating System: Ubuntu 14.04 LTS
* Java environment:
* JDK 7 either from OpenJDK or Oracle;
...
...
@@ -18,52 +18,59 @@ This guide provides the procedure to install the AuthZForce server from the `tar
## Installation
### Minimal
1. If you don't have a JDK 7 already installed, you may do it on the command-line as follows, depending on your JDK preference:
* If you prefer OpenJDK: `$ sudo aptitude install openjdk-7-jdk`
* If you prefer Oracle JDK, follow the instructions from [WEB UPD8](http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html). In the end, you should have the package `oracle-java7-installer` installed.
* If you prefer OpenJDK: `$ sudo aptitude install openjdk-7-jdk`
* If you prefer Oracle JDK, follow the instructions from [WEB UPD8](http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html). In the end, you should have the package `oracle-java7-installer` installed.
1. If you don't have Tomcat 7 already installed, you may do it on the command-line: `$ sudo aptitude install tomcat7`
1. Download AuthZForce server `tar.gz` distribution from the [Github project releases page](https://github.com/authzforce/server/releases/download/release-${project.version}/authzforce-ce-server-${project.version}.tar.gz>). You get a file called ``authzforce-ce-server-${project.version}.tar.gz``.
1. Download AuthZForce server tarball distribution from the [Maven Central Repository](http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/${project.version}/authzforce-ce-server-dist-${project.version}.tar.gz). You get a file called ``authzforce-ce-server-dist-${project.version}.tar.gz``.
1. Copy this file to the host where you want to install AuthZForce Server.
1. For security purposes, Tomcat should be run as an unprivileged user (i.e. not `root`). If you installed Tomcat as shown above, this user is `tomcat7`. Let us assume that `tomcat7` is the user (and group) that will run the Tomcat service in your case, and `/opt` is the directory where you want to install AuthZForce server. Please replace both names according to your setup. `$CATALINA_BASE` is a Tomcat environment-specific property, usually equal to `$CATALINA_HOME`, i.e. the root directory of your Tomcat installation ([more information](https://tomcat.apache.org/tomcat-7.0-doc/introduction.html)). If you installed Tomcat as shown above, `$CATALINA_BASE = /var/lib/tomcat7`. From the directory where you copied the `tar.gz` for installation, run the following commands:
1. For security purposes, Tomcat should be run as an unprivileged user (i.e. not `root`). If you installed Tomcat as shown above, this user is `tomcat7`. Let us assume that `tomcat7` is the user (and group) that will run the Tomcat service in your case, and `/opt` is the directory where you want to install AuthZForce server. Please replace both names according to your setup. `$CATALINA_BASE` is a Tomcat environment-specific property, usually equal to `$CATALINA_HOME`, i.e. the root directory of your Tomcat installation ([more information](https://tomcat.apache.org/tomcat-7.0-doc/introduction.html)). If you installed Tomcat as shown above, `$CATALINA_BASE = /var/lib/tomcat7`. From the directory where you copied the tarball for installation, run the following commands:
```shell
$ sudo tar xvzf authzforce-ce-server-${project.version}.tar.gz --directory /opt
1. If you did not use `/opt` as installation directory, replace **ALL** occurrences of `/opt` in the webapp context configuration file `authzforce-ce.xml` according to your setup.
1. You may restart Tomcat server now. For instance, if you installed Tomcat as shown above, do it as follows:
```shell
$ sudo service tomcat7 restart
```
**Known issue: lack of entropy may cause delays in Tomcat 7+ start up on virtual machines in particular: [more info on Entropy Source issue](https://wiki.apache.org/tomcat/HowTo/FasterStartUp#Entropy_Source). So beware.**
1. When the webapp is up and running, you should get a HTTP response with status code 200 to this HTTP request with curl tool (replace 8080 with the port that Tomcat is listening to):
```shell
$ curl --verbose--show-error--write-out'\n'--request GET http://localhost:8080/authzforce-ce/domains
```
Now you can start playing with the REST API as defined by the WADL document that you can retrieve with a wget command (will save the wadl to local file `authzforce.wadl`):
Tomcat default setup is not suitable for production! If you are targeting a production environment, you have to carry out extra installation and configuration steps to address non-functional aspects: security (including availability), performance, etc. For performance aspects, we strongly recommend reading and applying - when relevant - the guidelines from the following links:
-[Performance tuning best practices for VMware Apache Tomcat](http://kb.vmware.com/kb/2013486)
-[How to optimize Tomcat performance in production](http://www.genericarticles.com/mediawiki/index.php?title=How_to_optimize_tomcat_performance_in_production)
-[Apache Tomcat Tuning Guide for REST/HTTP APIs](https://javamaster.wordpress.com/2013/03/13/apache-tomcat-tuning-guide/)
-[Performance tuning best practices for VMware Apache Tomcat](http://kb.vmware.com/kb/2013486);
-[How to optimize Tomcat performance in production](http://www.genericarticles.com/mediawiki/index.php?title=How_to_optimize_tomcat_performance_in_production);
-[Apache Tomcat Tuning Guide for REST/HTTP APIs](https://javamaster.wordpress.com/2013/03/13/apache-tomcat-tuning-guide/).
Last but not least, please check the *More information* section below.
## Troubleshooting
If Tomcat fails to (re)start, check for any Tomcat high-level error in Tomcat log directory: `$CATALINA_BASE/logs`.
One common reason for failure is Tomcat default configuration may specify a value for the Java `Xmx` flag that is too low for the AuthZForce webapp. Make sure Tomcat is configured with `Xmx` at 1GB or more, 2 GB recommended. For example, in the official Tomcat package for Ubuntu 12.04, Xmx used to be 128m. You can fix this parameter as follows:
If Tomcat is started but AuthZForce webapp deployment fails, check for any webapp-specific error in log file: `$CATALINA_BASE/logs/authzforce-ce/error.log`
