We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.Security.AuthorizationPDP - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.AuthorizationPDP

From FIWARE Forge Wiki

(Difference between revisions)
Jump to: navigation, search
(Terms and definitions)
 

Latest revision as of 12:17, 10 October 2016

Name FIWARE.OpenSpecification.Security.AuthorizationPDP
Chapter Security,
Catalogue-Link to Implementation AuthZForce
Owner THALES, Cyril Dangerville (TS)


Contents

Preface

Within this document you find a self-contained open specification of a FIWARE generic enabler, please consult as well the FIWARE Product Vision, the website on http://www.fiware.org and similar pages in order to understand the complete context of the FIWARE platform.

Copyright

Copyright © 2014-2016 by THALES.

Legal Notice

Please check the following Legal Notice to understand the rights to use these specifications.

Overview

The Authorization PDP Generic Enabler provides two main features:

  • Authorization policy decision evaluation: This is the main feature of this GE as a PDP. Indeed, PDP stands for Policy Decision Point and its main feature consists to evaluate authorization decisions based on XACML policies and attributes related to a given access request (e.g. requester’s identity, requested resource, requested action), following the policy evaluation logic defined in the XACML standard. This feature is provided to external clients through a REST API that we call the PDP API, where PDP is short for the term Policy Decision Point defined by the XACML standard.
  • Authorization policy administration: creation, retrieval, update and removal of XACML policies. This feature is provided to external clients through a REST API that we call the PAP API, where PAP is short for the term Policy Administration Point defined by the XACML standard. This feature is necessary to support the previous feature. Indeed, it allows policy administrators (such as application developers potentially) to configure the XACML policies to be evaluated by the GE when calling the PDP API.

For more information on XACML, refer to the Basic Concepts section.

To have an overview of how the Authorization PDP GE can be used in FIWARE, especially by developers, and how it fits in the FIWARE architecture, please consider the figure below.

Authorization PDP - Architecture overview

To understand the various interactions going on in this picture, we will go through a typical scenario. Let us follow a typical scenario where some developer wants to define an authorization policy for his/her service, e.g. a RESTful web service, and then enforce this policy to control access to his/her application. We assume that the developer has registered his/her service like any other application in the Identity Management GE via the Application Developer Portal (see the Identity Management GE Architecture description for more information).

  1. Via the Application Developer Portal, the developer can define an authorization policy for his/her service using a GUI (graphical user interface). In this case, we can say that the developer plays the role of Application Security Administrator pictured on the above diagram. This role may be played by another person in the developer’s organization as well, such as a security officer or security architect working with the developer on the application. In any case, with the Developer Portal, this App Security Admin may define user roles specific to his/her service with the associated permissions expressed for example in a RESTful way (a permission HTTP method, and a resource URL path, ‘*’ used as a wildcard):
    1. Role ‘Reader’ can only do GET actions on resource /docs/*
    2. Role ‘Publisher’ can only do GET, POST and PUT on resource /docs/*
    3. Role ‘Administrator’ can do any operation on any resource (/*).
  2. When the App Security Admin (e.g. developer) has defined the access policy and decides to save and apply it, the IdM GE’s Access management module is called by the Developer Portal to process this policy. The module converts into a XACML policy and sends it to the PAP API of the Authorization PDP GE.
  3. The developer (or App Security Admin in general) may assign each of the defined roles to users of his/her choice.
  4. The developer deploys an instance of the PEP Proxy GE in front of his/her service (pictured as Protected Rest Service on the diagram above), as a HTTP reverse-proxy, and configures it with the URL to the IdM GE, the URL to the Authorization PDP GE (more specifically the PDP API endpoint), and the URL to the service API endpoint of his service. Note that in order to protect the communications with the PEP, especially on a production system, it is necessary to enable SSL on the PEP and therefore configure the SSL certificate and other SSL settings. For more information on this part, please refer to the PEP Proxy GE architecture description.

The developer publishes the endpoint of the PEP Proxy instance as the new endpoint of his/her service, and makes sure it cannot be bypassed, usually by means of network filtering (e.g. firewall).

Everything is now in place to enforce access control. From this point forward, every access request to the service (REST service in this case) goes like this:

  1. We assume that the access requester got a valid access token from the IdM GE before sending any request. It gets this token from the IdM GE (corresponding to the URL defined in the PEP configuration earlier). For more information on the process by which the requester may obtain an access token from the IdM, please refer to the Identity Management GE Architecture description.
  2. The access requester sends a request to the new published endpoint of protected service, which happens to be the PEP proxy, with the access token included in a specific HTTP header. For more details on this step, please refer to the PEP Proxy GE architecture description.
  3. The request is intercepted by the PEP Proxy. If the request does not have an access token (in the HTTP header) as expected by the PEP Proxy, the request is considered not authenticated and rejected by the PEP. Otherwise, the PEP extracts the access token from the header and sends it in a request to the IdM to validate the token, using the IdM token API. If the token is valid, the IdM replies with extra authorization info about the token, including the authenticated requester’s attributes known by the IdM, e.g. ID and role. For more details on this step, please refer to the PEP Proxy GE architecture description.
  4. The PEP sends a XACML Request to the Authorization PDP API with all this information about the requester and the access request, such as the requested action (HTTP method) and resource (URL path). The Authorization PDP GE evaluates the policy (defined by the developer and pushed via the Authorization PDP GE’s PAP API earlier) for the input XACML Request received from the PEP. At the end of the evaluation, the PDP GE finally returns an authorization decision (Permit or Deny) to the PEP.
  5. Depending on this decision, the PEP blocks (if Deny decision) or forwards (if Permit decision) the request to the service (REST service in this case). The application replies and the PEP forwards back the response to the requester, at last.

If you want to go into further details on the main interactions between the Authorization PDP GE and the other components shown on the picture above, please refer to the dedicated Main Interactions section.

Basic Concepts

It is useful at this point to give a quick overview of the OASIS XACML standard as it defines the essential parts of the GE features and APIs.

We can summarize it in three parts:

  • Policy language: XACML defines a XML data model for defining authorization policies, as well as the logic to follow to evaluate them in a given access request context. Rule, Policy (set of Rules), and PolicySet (set of Policy elements) constitute the main elements of the model. In short, 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.
  • Request-Response protocol: The XACML standard also defines a XML data model for the authorization decision request (XACML Request) that a PEP (described later) creates with all the necessary access request attributes and sends to the PDP API for evaluation; and the resulting response (XACML Response) that contains the final decision (Permit or Deny).
  • Architecture framework: The XACML standard also defines a high-level architecture that we are re-using and adapting in FIWARE Security Chapter, including the following major components:
    • Policy Decision Point (PDP): The PDP provides authorization decisions based on various attributes given at runtime by PEPs 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.
    • Policy Administration Point (PAP): 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.
    • Policy Enforcement Point (PEP): The PEP protects a given resource/service API – typically a REST API in FIWARE – and enforces the decision of the PDP whether to allow or deny a particular access request to the API. The PEP is worth mentioning here as it is the main component interacting with the PDP to control access to resources.

The PEP can be deployed as a security proxy that intercepts all HTTP(S) traffic to the Resource Server. This kind of PEP is specified in FIWARE as a GE (with associated Reference Implementation): The PEP Proxy GE. Therefore, please refer to the PEP Proxy GE architecture description for more information.

In some more complex use cases, e.g. with non-web services, it is not possible to delegate the PEP function to the PEP Proxy GE; it is better to develop a custom one, therefore the Custom PEP shown in the diagram of the Overview section.


Main Interactions

The main interactions are illustrated in the figure below, already shown in the overview but reminded here as we go into further details on the interactions with the GE and other components in FIWARE.

Authorization PDP - Main Interactions
  • Interactions with the GE’s PAP API: The RESTful PAP API is used by the Identity Management GE to have the access policies – defined by developers for their applications via the Developer Portal (graphical form of PAP) – pushed to the PDP GE in order to be enforced by the PDP. The IdM may also use it to store and retrieve the policies managed via the portal. The PAP API may also be used directly by any policy administration client (or any REST client whatsoever) that has been developed specifically for some use case, to address specific aspects of access control policy that the IdM GE’s developer portal cannot address. For example, the portal does not address the full complexity and expressiveness of XACML, and it is not its goal. But it is likely that some use cases will need to define policies that require specific features of XACML (functions, combining algorithms ...) that are not supported by the IdM GE’s portal.
The PAP API supports the usual HTTP methods (GET, PUT...) to create, read, update and delete policies. The data representation type is XML. The main type of XML element used in requests/responses is the XACML PolicySet as defined in the XACML schema.
  • Interactions with the GE’s PDP API: This REST API is used by PEPs such as the PEP Proxy GE for REST services, or a Custom PEP for other types of service (depending on the use case requirements or constraints), to request an authorization decision from the policy evaluation engine. The PEP sends a HTTP POST request to the API with a XACML Request (defined by the XACML schema) as body of the request. This request should contain all the necessary authorization attributes, mentioned in the policy enforced, for the PDP to be able to evaluate this policy. The PDP returns a XACML Response (defined by the XACML schema) that contains the Permit or Deny decision. It may also return Indeterminate if an error occurred during evaluation, for example, if some attribute was missing (not provided by the PEP). You can also define the policy in such a way that the PDP returns Deny instead of Indeterminate if such an error occurs, to avoid any issue on the PEP side.

Basic Design Principles

  • The architecture complies with the XACML standard.
  • All APIs (XACML Policy Administration API, XACML PDP API) are RESTful APIs.
  • The format of access control policies managed by the PAP and enforced by the PDP is defined by the XACML standard.
  • The PDP computes access decisions based on policies according to the XACML standard rules for policy evaluation (XACML engine).
  • The PDP and PAP should support multi-tenancy.

References

Detailed Specifications

Please refer to FIWARE Authorization PDP API Specification for a detailed specification of the Authorization PDP Generic Enabler's interfaces.

Re-utilised Technologies/Specifications

The GE specification is based on the following:

Terms and definitions

This section comprises a summary of terms and definitions introduced during the previous sections. It intends to establish a vocabulary that will be help to carry out discussions internally and with third parties (e.g., Use Case projects in the EU FP7 Future Internet PPP). For a summary of terms and definitions managed at overall FIWARE level, please refer to FIWARE Global Terms and Definitions

  • Access control: is the prevention of unauthorized use of a resource, including the prevention of use of a resource in an unauthorized manner (ITU-T Recommendation X.800). More precisely, access control is the protection of resources against unauthorized access; a process by which use of resources is regulated according to a security policy and is permitted by only authorized system entities according to that policy (RFC 2828).
  • XACML: OASIS standard for eXtensible Access Control Markup Language (XACML 3.0).
  • Policy Decision Point (PDP): The PDP provides authorization decisions based on various attributes and XACML policies. Attributes may come from the access request context as provided by PEPs (see below), such as the request URL, the HTTP method and especially the OAuth access token.
  • Policy Enforcement Point (PEP): the PEP protects a given resource/service provider’s API – typically a REST API in FIWARE - and enforces the decision of the PDP whether to allow or deny a particular access request from a client to the API.
  • Policy Administration Point (PAP): the PAP provides an interface for policy administrators to manage XACML policies to be enforced by the PDP.
Personal tools
Create a book