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 R4 - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.AuthorizationPDP R4

From FIWARE Forge Wiki

(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
{{Remark|This page corresponds with Release 4, please refer to [[Summary of FIWARE Open Specifications]] for the current Open Specs of the GEs of FIWARE}}
{{Open spec brief  
{{Open spec brief  
|Name= FIWARE.OpenSpecification.Security.AuthorizationPDP
|Name= FIWARE.OpenSpecification.Security.AuthorizationPDP

Latest revision as of 12:16, 10 October 2016

FIWARE WIKI editorial remark:
This page corresponds with Release 4, please refer to Summary of FIWARE Open Specifications for the current Open Specs of the GEs of FIWARE
Name FIWARE.OpenSpecification.Security.AuthorizationPDP
Chapter Security,
Catalogue-Link to Implementation AuthZForce
Owner THALES, Cyril Dangerville (TS)



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 © 2014-2016 by THALES.

Legal Notice

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


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.


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).
  • Account: A (user) account is “typically a formal business agreement for providing regular dealings and services between principal sand business service providers.” OASIS Security Assertion Markup Language (SAML).
  • Authentication (AuthN): We adopted the following definition of authentication from RFC 3588: "Authentication is “the act of verifying the identity of an entity (subject)".
TrustInCyberspace adds the term “level of confidence” to this definition:
Authentication is the process of confirming a system entity’s asserted identity with a specified, or understood, level of confidence.” This definition holds all necessary parts to examine authentication in broad sense. First of all it does not narrow the authentication to human users, but refers to a generic “system entity”. See authentication reference architecture description for a closer look at different identities that could be authenticated.
Secondly it introduces the often neglected concept of “level of confidence” which applies to each authentication of an identity. No computer program or computer user can definitely prove the identity of another party. There is no authentication method that can be secured against any possible identity-theft attack, be it physical or non-physical. It is only possible to apply one or more tests, which, if passed, have been previously declared to be sufficient to go on further. The problem is to determine which tests are sufficient, and many such are inadequate.
The original Greek word originates from the word 'authentes'='author'. This leads to the general field of claims and trust management, because authentication could also mean to verify the “author” / issuer of any claim.
The confirmation or validation process of authentication is actually done by presenting some kind of proof. This proof is normally derived from some kind of secret hold by the principal. In its simplest form the participant and the authentication authority share the same secret. More advanced concepts rely on challenge/response mechanisms, preventing the secrets to be transmitted. Refer to Authentication Technologies for a detailed list of authentication methods used today.
As stated above, each authentication method assures only some level of trust in the claimed identity, but none could be definite. Therefore it makes sense to distinguish the different authentication methods by an associated assurance level, stating the level of trust in the authentication process.
As this assurance level depends not only on the technical authentication method, but also on the overall computer system and even on the business processes within the organization (provisioning of identities and credentials), there is no ranking of the authentication methods here.
  • Authentication protocol: "Over-the-wire authentication protocols are used to exchange authentication data between the client and server application. Each authentication protocol supports one or more authentication methods. The OATH reference architecture provides for the use of existing protocols, and envisions the use of extended protocols which support new authentication methods as they are defined." (OATH)
  • Federation: The term federation “is used in two senses - "The act of establishing a relationship between two entities. An association comprising any number of service providers and identity providers.” OASIS Security Assertion Markup Language (SAML)
“A federation is a collection of realms that have established a producer-consumer relationship whereby one realm can provide authorized access to a resource it manages based on an identity, and possibly associated attributes, that are asserted in another realm.
Federation requires trust such that a relying party can make a well-informed access control decision based on the credibility of identity and attribute data that is vouched for by another realm.” WS-Federation @ IBM
Remark: Federation according to WS-Federation @ IBM is similar to the concept of a Circle of Trust.
  • Identifier: Identifiers can be understood as a dedicated, publicly known attribute of an identity that refers to that identity only. Typically, identifiers are valid within a specific domain. Special types of identifiers are valid globally, due to the use of popular domain naming and resolution protocols such as DNS, which implies addressing capabilities to the identity. OASIS Security Assertion Markup Language (SAML) defines identifier as follows:
An identifier is “a data object (for example, a string) mapped to a system entity that uniquely refers to the system entity. A system entity may have multiple distinct identifiers referring to it. An identifier is essentially a "distinguished attribute" of an entity.”
  • Identity (Digital): The term identity and its meaning have been discussed controversially in the “identity community” for many years. Until now, there is no commonly agreed definition of that notion. The IdM and AAA reference architecture applies the following three definitions of identity.
The Identity Gang defines the term digital identity as follows:
A digital identity is “a digital representation of a set of Claims made by one party about itself or another digital subject.”
The following comments were added:
A digital identity is just one set of claims about a digital subject. For any given digital subject there will typically be many digital identities.
A digital identity can be created on the fly when a particular identity transaction is desired or persistent in a data store to provide a representation that can be referenced.
A digital identity may contain claims made by multiple claimants.
A digital identity may be signed by a digital identity provider to provide assurance to a relying party.
This definition emphasizes two facts:
Normally, a principal (subject) has multiple digital identities or personas.
Identities are made out of attributes (claims).
Therefore, the scope of identity management in the reference architecture has two viewpoints: For once it focuses on identities and personas itself, and on the other side, it deals with the attributes of these identities and personas.
The Liberty Alliance Project (LAP) defines digital identity as follows:
Digital identity is “the essence of an entity. One’s identity is often described by one’s characteristics, among which may be any number of identifiers. A Principal may wield one or more identities.”
RSA uses the following definition of digital identity:
“Digital identity consists of an identity assertion and the characteristics, sometimes called attributes that are collected or observed through our computerized relationships. It is often as simple as a user name and password.”
The definition of RSA adds one important aspect to the identity discussion: Even the simplest user name and password combinations without any additional attributes or claims constitute an identity.
  • Identity context: is “the surrounding environment and circumstances that determine meaning of digital identities and the policies and protocols that govern their interactions.” (Identity Gang)
  • Identity management (IdM): comprises “the management of identity information both internally and when it is passed from one entity to another.” Open Mobile Alliance (OMA)
  • Identity provider: The Open Mobile Alliance (OMA) defines the term identity provider (IdP) as follows - An identity provider is “a special type of service provider […] that creates, maintains, and manages identity information for principals, and can provide […] assertions to other service providers within an authentication domain (or even a circle of trust).”
Another notion defines identity provider as “an agent that issues a digital identity [that] is acting on behalf of an issuing Party.” (Identity Gang)
The following definition of identity provider descends from WS-Federation @ IBM: “An identity provider is an entity that acts as an authentication service to end requestors and as data origin authentication service to service providers […]. Identity providers are trusted (logical) 3rd parties which need to be trusted both by the requestor […] and the service provider which may grant access to valuable resources and information based upon the integrity of the identity information provided by the identity provider.”
The Identity Provider is part of the Identity Management infrastructure.
  • Single sign-on: is “From a Principal’s perspective, single sign-on encompasses the capability to authenticate with some system entity—[…] an Identity Provider - and have that authentication honored by other system entities, [termed] Service Providers […]. Note that upon authenticating with an Identity Provider, the Identity Provider typically establishes and maintains some notion of local session state between itself and the Principal’s user agent. Service Providers may also maintain their own distinct local session state with a Principal’s user agent.” Liberty Alliance Project (LAP)
Personal tools
Create a book