AuthZForce (Community Edition)

Last modified by Cyril Dangerville on 2017/06/17 01:01

Button-OW2con16-Short149x65.png OW2con16AwardsResults_thumbnail.jpgBest Project Award

License badge Documentation badge Docker badge  https://bestpractices.coreinfrastructure.org/projects/389/badge 

What is AuthZForce?

The AuthZForce project provides an Attribute-Based Access Control (ABAC) framework compliant with the OASIS XACML standard v3.0, that mostly consists of an authorization policy engine and a RESTful authorization server. It was primarily developed to provide advanced access control for Web Services or APIs, but is generic enough to address all kinds of access control use cases.
You can use AuthZForce in two ways depending on your needs:

  • Java API: AuthZForce provides a XACML PDP (Policy Decision Point) engine as a Java library so that applications can instantiate and use an embedded XACML PDP easily with Java. This API is provided by AuthzForce Core.
  • Web API: AuthZForce provides a multi-tenant HTTP/REST API to PDPs and PAPs (Policy Administration Points) that web clients can call to manage policies, request authorization decisions, etc. This API is provided by AuthzForce Server.

If you are interested in using the Web API, go to AuthZForce Server project.

AuthzForce Features

PDP (Policy Decision Point)

Applies to AuthzForce Core and AuthzForce Server.

AuthzForce provides XACML PDP features:

OASIS XACML v3.0 Standards compliance

For further details on what is actually supported with regards to the XACML specifications, please refer to the conformance tests README.

Security

  • Detection of circular XACML policy references (PolicyIdReference/PolicySetIdReference); 
  • Control of the maximum XACML PolicyIdReference/PolicySetIdReference depth;
  • Control of the maximum XACML VariableReference depth;

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), 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.);

Attribute sources a.k.a. PIPs (Policy Information Points)

Authzforce is able to retrieve attributes from a XACML Request of course, but also from other attribute sources, also known as Policy Information Points (PIP) in the XACML standard, e.g. LDAP or SQL database servers, REST services or X.509 attribute certificate repository. Besides, its plugin architecture enables developers to support custom attribute sources by adding new Attribute Provider plugins. More info in the Extensibility points section below.

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: 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; such attribute sources are also known as Policy Information Points (PIPs) in XACML terms, i.e. you implement a new Attribute Provider to support a new type of PIP.
  • 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);
  • 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);
  • Ref Policy Providers: you may plug custom policy providers into the PDP engine to allow it to resolve PolicyIdReference or PolicySetIdReference;
  • 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;
  •  Java extension mechanism to switch HashMap/HashSet implementations (e.g. to get different performance results).

PIP (Policy Information Point)

Applies to AuthzForce Core and AuthzForce Server.

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

PAP (Policy Administration Point)

Applies to AuthzForce Server only.

AuthzForce provides XACML PAP features:

  • 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

Applies to AuthzForce Server only.

High availability and load-balancing

Applies to AuthzForce Server only.

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

Versions

See the change log file according to the Keep a CHANGELOG conventions.

License

See the license file.

Getting started with AuthzForce Core

If you are rather interested by the AuthzForce Server instead, go to the AuthZForce Server project

You can either build Authzforce PDP library from the source code after cloning the git repository, or use the latest release from Maven Central with this information:

  • groupId: org.ow2.authzforce;
  • artifactId: authzforce-ce-core-pdp-engine;
  • packaging: jar.

If you want to use the experimental features (see previous section) as well, you need to use an extra Maven dependency:

  • groupId: org.ow2.authzforce;
  • artifactId: authzforce-ce-core-pdp-testutils;
  • packaging: jar.

To get started using a PDP to evaluate XACML requests, instantiate a new PDP instance with one of the methods: org.ow2.authzforce.core.pdp.impl.BasePdpEngine#getInstance(...). The parameters are:

  1. confLocation: location of the configuration file (mandatory): this file must be an XML document compliant with the PDP configuration XML schema. You can read the documentation of every configuration parameter in that file. If you don't use any XML-schema-defined PDP extension (AttributeProviders, PolicyProviders...), this is the only parameter you need, and you can use the simplest method BasePdpEngine#getInstance(String confLocation) to load your PDP. Here is an example of configuration:
    <?xml version="1.0" encoding="UTF-8"?> <pdp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://authzforce.github.io/core/xmlns/pdp/5.0" version="5.0.0"> <rootPolicyProvider id="rootPolicyProvider" xsi:type="StaticRootPolicyProvider" policyLocation="${PARENT_DIR}/policy.xml" /> </pdp>
       This is a basic PDP configuration with basic settings and the root policy (XACML Policy document) loaded from a file policy.xml (see this one for an example) located in the same directory as this PDP configuration file. 
  2. catalogLocation: location of the XML catalog (optional, required only if using one or more XML-schema-defined PDP extensions): 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 XML catalog in the sources as an example. This is the one used by default if none specified.
  3. extensionXsdLocation: location of the PDP extensions schema file (optional, required only if using one or more PDP extensions): 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 in the sources as an example.

As a result of getInstance(...), you get an instance of BasePdpEngine with which you can evaluate a XACML Request directly by calling the evaluate(Request...) methods; or 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 more efficient native model by calling evaluate(ImmutablePdpDecisionRequest) or (multiple decision requests with evaluate(List<ImmutablePdpDecisionRequest>)). In order to build a ImmutablePdpDecisionRequest, you may use the request builder returned by BasePdpEngine#newRequestBuilder(...).  Please look at Javadoc for more information.

Our PDP implementation uses SLF4J for logging so you can use any SLF4J implementation to manage logging. As an example, we use logback for testing, so you can use logback.xml as an example for configuring loggers, appenders, etc.

If you are using Java 8, make sure the following JVM system property is set before execution: javax.xml.accessExternalSchema = http

Example of usage and code with a web service authorization module

For an example of using an AuthzForce PDP engine in a real-life use case, please refer to the JUnit test class EmbeddedPdpBasedAuthzInterceptorTest and the Apache CXF authorization interceptor EmbeddedPdpBasedAuthzInterceptor. The test class runs a test similar to @coheigea's XACML 3.0 Authorization Interceptor test 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 that plays the role of PEP (Policy Enforcement Point in XACML jargon), i.e. it extracts the various authorization attributes (user ID and roles, web service name, operation...) and requests a decision from a local PDP with these attributes, then enforces the PDP's decision, i.e. forwards the request to the web service implementation if the decision is Permit, else rejects it. For more information, see the Javadoc of EmbeddedPdpBasedAuthzInterceptorTest.

Support

If you are experiencing problems using AuthzForce, please report your problem via the Issue Tracker.
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 the Authzforce contact mailing list.

Tags:
Created by Cyril Dangerville on 2016/07/06 11:24
    
This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 6.4.4 - Documentation