AuthZForce Server (Community Edition)

This project is part of FIWARE. More info on the FIWARE catalogue.

AuthZForce Server provides a multi-tenant RESTful API to Policy Administration Points (PAP) and Policy Decision Points (PDP) supporting Attribute-Based Access Control (ABAC), as defined in the OASIS XACML 3.0 standard.

AuthZForce Server is also the Reference Implementation (GEri) of FIWARE Authorization PDP Generic Enabler (GE). More info on the FIWARE catalogue.

Go to the releases page for specific release info: downloads (Linux packages), Docker image, release notes, and documentation.

If you are interested in using an embedded XACML-compliant PDP in your Java applications, AuthZForce also provides a PDP engine as a Java library in Authzforce core project.

Features

PDP (Policy Decision Point)

• Compliance with the following OASIS XACML 3.0 standards:
  • XACML v3.0 Core standard: all mandatory and optional features are supported, except:
    • 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.
  • XACML v3.0 Core and Hierarchical Role Based Access Control (RBAC) Profile Version 1.0
  • XACML v3.0 Multiple Decision Profile Version 1.0 - Repeated attribute categories (urn:oasis:names:tc:xacml:3.0:profile:multiple:repeated-attribute-categories).
  • Experimental support for:
    • XACML Data Loss Prevention / Network Access Control (DLP/NAC) Profile Version 1.0: only dnsName-value datatype and dnsName-value-equal function are supported;
    • XACML 3.0 Additional Combining Algorithms Profile Version 1.0: on-permit-apply-second policy combining algorithm;
    • XACML v3.0 Multiple Decision Profile Version 1.0 - Requests for a combined decision (urn:oasis:names:tc:xacml:3.0:profile:multiple:combined-decision).
• Detection of circular XACML policy references (PolicySetIdReference);
• Control of the maximum XACML PolicySetIdReference depth;
• Control of the maximum XACML VariableReference depth;
• 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), 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;
  • Attribute Providers a.k.a. PIPs (Policy Information Points): you may plug custom attribute providers into the PDP engine to allow it to retrieve attributes from other attribute sources (e.g. remote service) than the input XACML Request during evaluation;
  • Request Filter: you may customize the processing of XACML Requests before evaluation by the PDP core engine (e.g. used for implementing XACML v3.0 Multiple Decision Profile Version 1.0 - Repeated attribute categories);
  • Result Filter: you may customize the processing of XACML Results after evaluation by the PDP engine (e.g. used for implementing XACML v3.0 Multiple Decision Profile Version 1.0 - Requests for a combined decision);

PIP (Policy Information Point)

AuthzForce provides XACML PIP features in the form of Attribute Providers. More information in the previous section.

PAP (Policy Administration Point)

• Policy management: create/read/update/delete multiple policies and references from one to another (via PolicySetIdReference)
• Policy versioning: create/read/delete multiple versions per policy.
• Configurable root policy ID/version: top-level policy enforced by the PDP may be any managed policy (if no version defined in configuration, the latest available is selected)
• Configurable maximum number of policies;
• Configurable maximum number of versions per policy.
• Optional policy version rolling (when the maximum of versions per policy has been reached, oldest versions are automatically removed to make place).

REST API

• Provides access to all PAP/PDP features mentioned in previous sections with possibility to have PDP-only instances (i.e. without PAP features).
• Multi-tenant: allows to have multiple domains/tenants, each with its own PAP/PDP, in particular its own policy repository.
• Conformance with REST Profile of XACML v3.0 Version 1.0
• Supported data formats: JSON, XML, Fast Infoset.
• Defined in standard Web Application Description Language and XML schema so that you can automatically generate client code.

High availability and load-balancing

• Integration with file synchronization tools (e.g. csync2) or distributed filesystems (e.g. NFS and CIFS) to build clusters of AuthZForce Servers.

Distribution (downloads)

Every release is distributed as follows:

• Ubuntu/Debian package (recommended option): .deb;
• Other Linux distributions: .tar.gz;
• Docker image.

For download links, please go to the specific release page.

Documentation

For links to the documentation of a release, please go to the specific release page.

Examples of usage and PEP code with a web service authorization module

For an example of using an AuthzForce Server's RESTful PDP API in a real-life use case, please refer to the JUnit test class RESTfulPdpBasedAuthzInterceptorTest and the Apache CXF authorization interceptor RESTfulPdpBasedAuthzInterceptor. The test class runs a test similar to @coheigea's XACML 3.0 Authorization Interceptor test but using AuthzForce Server as PDP 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 RESTfulPdpBasedAuthzInterceptor 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 with these attributes from a remote PDP provided by AuthzForce Server, 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 RESTfulPdpBasedAuthzInterceptorTest.

Support

Use the Issues tab on the Github repository page. Please include as much information as possible; the more we know, the better the chance of a quicker resolution:

• Software version
• Platform (OS and JDK)
• 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.
• Log output can be useful too; sometimes enabling DEBUG logging can help;
• Your code & configuration files are often useful.

If you wish to contact the developers for other reasons, use Authzforce contact mailing list.

Contributing

Documentation

The sources for the manuals are located in fiware repository.

Releasing

1. From the develop branch, prepare a release (example using a HTTP proxy):

   
   $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=8080 jgitflow:release-start

2. Update the AUTHZFORCE_SERVER_VERSION ENV variable to the new version in Dockerfile.
3. Update the changelog with the new version according to keepachangelog.com.
4. Commit
5. Perform the software release (example using a HTTP proxy):

   
   $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=8080 jgitflow:release-finish

   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:

   
   $ mvn -Dhttps.proxyHost=proxyhostname -Dhttps.proxyPort=8080 -DnoDeploy=true jgitflow:release-finish

   More info on jgitflow: http://jgitflow.bitbucket.org/
6. Connect and log in to the OSS Nexus Repository Manager: https://oss.sonatype.org/
7. Go to Staging Profiles and select the pending repository authzforce-*... you just uploaded with jgitflow:release-finish
8. Click the Release button to release to Maven Central.
9. When the artifacts have been successfully published on Maven Central, follow the instructions in the Release section of fiware repository.
10. Build the Dockerfile by triggering Docker automated build on the current Github release branch in authzforce-ce-server's Docker repository (Build Settings). Check the result in Build Details.
11. Update the versions in badges at the top of this file.
12. Create a release on Github with a description based on the release description template, replacing M/m/P with the new major/minor/patch versions.