Copyright © 2014-2016 by THALES.
This specification defines a RESTful API of an Authorization Policy Decision Point (PDP) compliant with the OASIS XACML standard. More specifically, it defines RESTful interfaces for:
Managing XACML-compliant authorization policies;
Requesting authorization decisions based on those policies, in a XACML-compliant request-response format;
Managing multiple PDPs, one per domain (aka tenant), in order to provide multi-tenancy.
This APIARY blueprint gives a user-friendly description of the API. However, the official API reference is available in a WADL (Web Application Description Language) and XML schema files on the Github repository of AuthZForce REST API model project. From this WADL (and associated XSD files), you can generate code automatically for various languages, e.g. Apache CXF's WADL2Java plugin for Java.
This is a work in progress and is changing on a daily basis.
A Policy is a set of Rules, and a PolicySet is a set of Policy elements. A Rule consists of a condition on the access request attributes, and a decision – Permit or Deny - to apply if the condition holds true for the request. A Policy (resp. PolicySet) combines multiple Rules (resp. Policies) and therefore multiple decisions together in various ways (defined in the standard) to make the final decision.
The PDP provides authorization decisions based on various attributes given at runtime by PEPs (Policy Enforcement Points) about each incoming access request, and XACML policies that define multiple rules checking whether those attributes (and therefore the access request) satisfy certain conditions. The attributes provided by the PEP (see below) about each access request may be attributes about the request itself: The request URL, the HTTP method; about the requester: The access requester ID, requester role. The PDP may add attributes to the context on its own, such as the current date and time when the requested is received. By replacing all the attribute references in the policy with these input values, PDP is able to evaluate the policy and determine whether the access should be granted.
The PAP provides an interface for policy administrators to manage XACML policies to be enforced by the PDP. This endpoint is provided by the Authorization PDP GE as well as a RESTful API interface. The IdM GE also provides a form of graphical interface for the PAP, as part of its access management feature. This feature actually uses the Authorization PDP GE’s PAP API as backend.
The API is designed to be multi-tenant, i.e. it allows users or organizations to work on authorization policies in complete isolation from each other. In this document, we use the term domain instead of tenant. In this context, a domain mostly consists of a specific dedicated PDP with specific policies. We may use the terms domain, administration domain and policy administration domain interchangeably in this document.
This specification is licensed under the FIWARE Open Specification License (implicit patents license).
All the interfaces described by this specification are mandatory and must be implemented in order to be compliant with.
Policy administration domains.
Create a new administration domain with defined properties, including one called externalId
. We use the same definition for this property as in the SCIM schema, § 3.1.
The response is the relative link to the REST resource created for the domain with a unique (opaque) ID assigned by the service.
Retrieve links to domains.
ParametersIf specified, only a link to the domain with a matching externalId
is returned, or none if no match.
Policy administration domain, dedicated to specific tenant or project or workspace, logically isolated from other domains
ParametersDomain ID
Retrieves links to sub-resources in the domain. This must include a link to the PDP (/pdp
as described later on) as specified by the REST Profile of XACML v3.0 Version 1.0, in test assertion urn:oasis:names:tc:xacml:3.0:profile:rest:assertion:home:pdp.
Delete the domain.
Policy administration domain properties
Update the properties of the domain. In this example, we change the externalId
and description.
Get the properties of the domain.
Policy Administration Point interface to manage the policies of the domain.
Add/update a policy (XACML PolicySet
) in the domain. The response is the relative link to the REST resource created for the policy version.
If there is no existing policy with a PolicySetId
matching the one in the request, this adds a new policy resource.
If a policy exists with same PolicySetId
but a different Version
, this adds a new resource for this new policy version under the policy resource.
If a policy exists with the same PolicySetId
and Version
, this must raise a conflict error and the operation must be canceled.
Get the list of domain's policies. The response is the list of links to all policy resources.
A policy in the domain.
ParametersPolicy ID, more precisely the XACML PolicySetId
.
Get the policy, i.e. the links to all versions of the policy.
Delete the policy, i.e. all policy versions. The response is the list of all the versions of the removed policy before removal.
A policy version.
ParametersPolicy version, more precisely the XACML PolicySet
Version
.
Get a specific version of a policy.
Delete a specific version of a policy. The response is the removed policy version.
Policy Administration Point interface to manage PDP properties:
One or more optional feature
elements: extra implementation-specific feature ID. A feature
element may have a type
attribute to indicate the category/type of feature, and a enabled
attribute to indicate whether the feature is actually enabled or not.
One mandatory rootPolicyRefExpression
element of type {urn:oasis:names:tc:xacml:3.0:core:schema:wd-17}IdReferenceType
(XACML v3.0): expression (with version pattern(s)) to be matched by the PolicySet's PolicySetId
and Version
to be enforced by the PDP as root policy. This policy and any other policy referenced (directly or indirectly) from it via XACML PolicySetIdReference must correspond to a resource under URL path '/policies'.
The documentation of any implementation of this GE must mention what is the default value for this element.
Get a specific version of a policy.
Policy Decision Point.
Headers
Content-Type: application/xml
Body
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
externalId="my.test.domain">
<description>This is a test domain.</description>
</domainProperties>
Headers
Content-Type: application/xml
Body
<link xmlns="http://www.w3.org/2005/Atom" rel="item" href="1234ABCD" title="1234ABCD"/>
Headers
Content-Type: application/xml
Body
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
externalId="my.test.domain0">
<description>This is a test domain and I want to use it.</description>
</domainProperties>
Headers
Content-Type: application/xml
Body
<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
externalId="my.test.domain0">
<description>This is a test domain and I want to use it.</description>
</domainProperties>
Headers
Content-Type: application/xml
Body
<PolicySet xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicySetId="P1" Version="1.0" ... />
Headers
Content-Type: application/xml
Body
<link xmlns="http://www.w3.org/2005/Atom" rel="item" href="P1/1.0" title="Policy 'P1' v1.0"/>
Headers
Content-Type: application/xml
Body
<pdpPropertiesUpdate
xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5">
<feature
type="urn:ow2:authzforce:feature-type:pdp:request-filter"
enabled="true">urn:ow2:authzforce:feature:pdp:request-filter:multiple:repeated-attribute-categories-lax</feature>
...(content omitted)...
<rootPolicyRefExpression>root</rootPolicyRefExpression>
</pdpPropertiesUpdate>
Headers
Content-Type: application/xml
Body
<pdpProperties
xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
lastModifiedTime="2016-05-28T14:21:35.730Z">
<feature
type="urn:ow2:authzforce:feature-type:pdp:request-filter"
enabled="false">urn:ow2:authzforce:feature:pdp:request-filter:multiple:repeated-attribute-categories-strict</feature>
<feature
type="urn:ow2:authzforce:feature-type:pdp:request-filter"
enabled="true">urn:ow2:authzforce:feature:pdp:request-filter:multiple:repeated-attribute-categories-lax</feature>
...(content omitted)...
<rootPolicyRefExpression>root</rootPolicyRefExpression>
</pdpProperties>