FIWARE Authorization PDP API Specification

DATE: 15 January 2016

Editors

Copyright © 2014-2016 by THALES.

Abstract

This specification defines the FIWARE Authorization PDP API. FIWARE Authorization PDP is short for FIWARE Authorization PDP Generic Enabler which enables PEPs (Policy Enforcement Points) to get an authorization decision for a given access request, based on access control policies, and various attributes in the context of the access request: the requester, the requested resource, the requested action, etc. The API follows the REST architecture style, and complies with XACML v3.0. XACML (eXtensible Access Control Markup Language) is a OASIS standard for authorization policy syntax and evaluation logic, as well as for the authorization decision request/response format. The PDP (Policy Decision Point) and the PEP (Policy Enforcement Point) terms are defined in the XACML standard.

REST API

Status of this document

This is a work in progress and is changing on a daily basis.

This specification is licensed under the FIWARE Open Specification License.

Specification

Introduction

The FIWARE Authorization PDP API 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 for a specific release is available in a WADL (Web Application Description Language) and XML schema files on the catalogue entry. From this WADL (and associated XSD files), you can generate code automatically for various languages, e.g. Apache CXF's WADL2Java plugin for Java.

Terminology

Policy and PolicySet

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.

PDP (Policy Decision Point)

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.

PAP (Policy Administration Point)

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.

Domain

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.

Conformance

All the interfaces described by this specification are mandatory and must be implemented in order to be compliant with.

API Specification

Default

Domains

[/domains]

Policy administration domains.

Add domain

POST /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.

Request (application/xml)
Response 200 (application/xml)

Get domains

GET /domains{?externalId}

Retrieve links to domains.

Parameters
externalId (Optional, string)
If specified, only a link to the domain with a matching externalId is returned, or none if no match.
Response 200 (application/xml)

Domain

[/domains/{domainId}]

Policy administration domain

Parameters
domainId (Required, string)
Domain ID

Delete domain

DELETE /domains/{domainId}

Delete the domain.

Response 200 (application/xml)

Domain properties

[/domains/{domainId}/properties]

Policy administration domain properties

Update domain properties

PUT /domains/{domainId}/properties

Update the properties of the domain. In this example, we change the externalId and description.

Request (application/xml)
Response 200 (application/xml)

Get domain properties

GET /domains/{domainId}/properties

Get the properties of the domain.

Response 200 (application/xml)

Domain PAP - Policies

[/domains/{domainId}/pap/policies]

Policy Administration Point interface to manage the policies of the domain.

Add/update a policy

POST /domains/{domainId}/pap/policies

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.

Request (application/xml)
Response 200 (application/xml)

Get policies

GET /domains/{domainId}/pap/policies

Get the list of domain's policies. The response is the list of links to all policy resources.

Response 200 (application/xml)

Domain PAP - Policy

[/domains/{domainId}/pap/policies/{policyId}]

A policy in the domain.

Parameters
policyId (Required, string)
Policy ID, more precisely the XACML PolicySetId.

Get policy

GET /domains/{domainId}/pap/policies/{policyId}

Get the policy, i.e. the links to all versions of the policy.

Response 200 (application/xml)

Delete policy

DELETE /domains/{domainId}/pap/policies/{policyId}

Delete the policy, i.e. all policy versions. The response is the list of all the versions of the removed policy before removal.

Response 200 (application/xml)

Domain PAP - Policy version

[/domains/{domainId}/pap/policies/{policyId}/{version}]

A policy version.

Parameters
version (Required, string)
Policy version, more precisely the XACML PolicySet Version.

Get policy version

GET /domains/{domainId}/pap/policies/{policyId}/{version}

Get a specific version of a policy.

Response 200 (application/xml)

Delete policy version

DELETE /domains/{domainId}/pap/policies/{policyId}/{version}

Delete a specific version of a policy. The response is the removed policy version.

Response 200 (application/xml)

Domain PDP

[/domains/{domainId}/pdp]

Policy Decision Point.

Request authorization decision

POST /domains/{domainId}/pdp
Request (application/xml)
Response 200 (application/xml)

Examples

Default

Domains

[/domains]
Add domain
POST /domains
Request (application/xml)

Headers

Content-Type: application/xml

Body

<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" 
    externalId="my.test.domain">
    <description>This is a test domain.</description>
</domainProperties>
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<link xmlns="http://www.w3.org/2005/Atom" rel="item" href="1234ABCD" title="1234ABCD"/>
Go to specification
Get domains
GET /domains{?externalId}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="1234ABCD" title="1234ABCD"/>
</resources>
Go to specification

Domain

[/domains/{domainId}]
Delete domain
DELETE /domains/{domainId}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" 
    externalId="my.test.domain">
    <description>This is a test domain.</description>
</domainProperties>
Go to specification

Domain properties

[/domains/{domainId}/properties]
Update domain properties
PUT /domains/{domainId}/properties
Request (application/xml)

Headers

Content-Type: application/xml

Body

<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
Go to specification
Get domain properties
GET /domains/{domainId}/properties
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<domainProperties xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" 
    externalId="my.test.domain0">
    <description>This is a test domain and I want to use it.</description>
</domainProperties>
Go to specification

Domain PAP - Policies

[/domains/{domainId}/pap/policies]
Add/update a policy
POST /domains/{domainId}/pap/policies
Request (application/xml)

Headers

Content-Type: application/xml

Body

<PolicySet xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicySetId="P1" Version="1.0" ... />
Response 200 (application/xml)

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"/>
Go to specification
Get policies
GET /domains/{domainId}/pap/policies
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="P1" title="P1"/>
    <atom:link rel="item" href="P1" title="P2"/>
    ...
</resources>
Go to specification

Domain PAP - Policy

[/domains/{domainId}/pap/policies/{policyId}]
Get policy
GET /domains/{domainId}/pap/policies/{policyId}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="1.0" title="1.0"/>
    <atom:link rel="item" href="1.1" title="1.1"/>
    <atom:link rel="item" href="2.0" title="2.0"/>
    ...
</resources>
Go to specification
Delete policy
DELETE /domains/{domainId}/pap/policies/{policyId}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<resources xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/4" xmlns:atom="http://www.w3.org/2005/Atom"> 
    <atom:link rel="item" href="1.0" title="1.0"/>
    <atom:link rel="item" href="1.1" title="1.1"/>
    <atom:link rel="item" href="2.0" title="2.0"/>
    ...
</resources>
Go to specification

Domain PAP - Policy version

[/domains/{domainId}/pap/policies/{policyId}/{version}]
Get policy version
GET /domains/{domainId}/pap/policies/{policyId}/{version}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<PolicySet xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicySetId="P1" Version="1.0" ... />
Go to specification
Delete policy version
DELETE /domains/{domainId}/pap/policies/{policyId}/{version}
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<PolicySet xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" PolicySetId="P1" Version="1.0" ... />
Go to specification

Domain PDP

[/domains/{domainId}/pdp]
Request authorization decision
POST /domains/{domainId}/pdp
Request (application/xml)

Headers

Content-Type: application/xml

Body

<Request xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" ... />
Response 200 (application/xml)

Headers

Content-Type: application/xml

Body

<Response xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17" ... />
Go to specification

References