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.PEPProxy - FIWARE Forge Wiki


From FIWARE Forge Wiki

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

Latest revision as of 12:08, 10 October 2016

Name FIWARE.OpenSpecification.Security.PEP Proxy Generic Enabler
Chapter Security,
Catalogue-Link to Implementation Wilma
Owner UPM, Alvaro Alonso



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 © 2016 by UPM. All Rights Reserved.

Legal Notice

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


A Policy Enforcement Point (PEP) is a component that protects resources against unauthorized access; unauthorized meaning: which does not comply with the access control policy applicable for these resources. It represents the final piece of the larger suite of Identity and Access Management GEs, of which we already mentioned the IdM and the Authorization PDP in previous sections. The PEP is the one intercepting each access request to the resource, but relies on the IdM to authenticate the request, and on the PDP to authorize it (deny of permit). In particular, on the contrary to the IdM and PDP, the PEP understands the particular API requests and protocols for accessing the resource under its protection. It also knows how to query the authentication and authorization APIs of the IdM and PDP. Last but not least, the PEP knows where and how to extract which information from the request that is necessary for authentication and authorization, and how to send it to the IdM and PDP to do just that.

In the case of the PEP Proxy GE, the protected resource is a HTTP service (API), e.g. a REST service, for which the GE plays the role of reverse proxy and is deployed as such. In this configuration, it is critical that any access request goes through the PEP proxy before reaching the protected service. To prevent any bypass, the application developer, usually with the help of the system and network administrators of the IT infrastructure where the application is deployed, makes sure that the proper perimeter security controls, e.g. firewall rules, are in place, and the application server (where the protected application is deployed) is not listening on ports reachable from outside except the one used by the PEP proxy. If the PEP proxy is deployed locally on the same host, then the application server only needs to listen locally. If the PEP Proxy is deployed on a different network from the application, it may result in communications going from the PEP Proxy server to the application server over an untrusted or uncontrolled network, e.g. Internet. In this case, it is critical to set up a secure channel between the two servers or two networks to protect the confidentiality and integrity of the communications, e.g. with TLS. We recommend that security-unaware developers avoid this last situation whenever possible.

Besides the PEP Proxy’s own TLS server certificate setup, the developer must configure the PEP Proxy with the HTTPS URL to the IdM GE for token validation. As the communications with the IdM GE must be secured, the PEP proxy must be configured to trust the IdM GE’s TLS certificate or the issuer certificate, i.e. a Certificate Authority (CA). Likewise, the PEP Proxy configuration must include the HTTPS URL to the Authorization PDP GE for authorization and trust the PDP GE’s certificate or issuing CA. Besides, the developer must configure the URL to the protected service API endpoint, so that the PEP Proxy knows where to forward the requests.

Furthermore, we assume that the developer has registered his application in the IdM GE, including the credentials for authenticating the application, and he/she (or any application security administrator in the developer’s organization) has configured an authorization policy for this application (REST service), either via the graphical interface of the Developer Portal, calling the Authorization PDP GE’s PAP API as backend; or sending (with a REST client) the policy directly in XACML format to the same PAP API. Please refer to the Authorization PDP GE (Overview) section for more information.

The PEP proxy GE is now able to intercept each incoming access request to the service and perform the authentication and authorization workflow according to the figure below:

PEP Proxy - Architecture overview
  1. It is expected that the requester has authenticated to the IdM GE using OAuth2 flow, and got an access token from the IdM GE as a result. (For more information, please refer to the Identity Management GE architecture description.)
  2. The requester sends the API request with the token included as the PEP Proxy GE expects, that is to say in a specific HTTP header in a specific format – depending on the GE implementation and configuration. For example, the PEP Proxy GE reference implementation supports access tokens in the Authorization header as defined by the OAuth 2.0 Bearer Token standard (IETF RFC 6750). In any case, In order to protect the confidentiality of access tokens in transit, the access request must be sent by the requester to the PEP over TLS (HTTPS), following the MUST requirement in Section 10.3 of OAuth 2.0 specification (IETF RFC 6749). This implies that the PEP proxy must have TLS enabled with a valid server certificate.
  3. When the PEP Proxy receives an access request, it extracts the access token from the specific request header mentioned previously and sends it to the IdM GE for validation. If it is valid, the IdM GE returns the validation result and other token-related information, such as information about the authenticated user (e.g. user role). If the token turns out not valid, the request is not authenticated therefore denied.
  4. The PEP Proxy sends to the Authorization PDP API an XACML authorization decision request that contains this IdM-issued information with other information about the access request: Requested resource ID, action ID (HTTP method), etc. For instance, for a REST API request, the PEP Proxy sends the URL requested for the resource, the HTTP method for the action ID, and authenticated user attributes. The Authorization PDP GE computes the authorization decision – Permit or Deny – and returns it to the PEP
  5. If PDP’s decision is Permit, the PEP forwards the API request to the protected service, and forwards the response back to the requester. If the decision was Deny, the PEP denies the request, for instance replies with a HTTP response 403 (Forbidden).

Basic Concepts

The main concepts of this section are:

  • Policy Enforcement Point (PEP) that this PEP Proxy GE represents;
  • Policy Decision Point (PDP), that this PEP Proxy enforces decisions of.

Please refer to the Basic Concepts section of the Authorization PDP GE architecture description for more information.

Main Interactions

The figure in the Overview section gave an overview of the GE’s main interactions. To summarize on the subject, we can say that the PEP Proxy GE interacts with two components in order to check authentication and authorization:

  • Identity Management GE: When PEP Proxy receives a request, it retrieves the authentication token from the specific header and validates it with the Identity Management GE.
  • Authorization PDP GE: If the component is configured to check not only the authentication but also the authorization, PEP Proxy will check with Authorization PDP if the user (from the token) has the correct permissions to access the resource specified in the request.

Basic Design Principles

  • Compatibility with REST APIs;
  • HTTP Reverse-proxy capabilities;
  • Gradual authentication and authorization with following options:
    • Simple reverse-proxy functionality for whitelist of URLs (no authentication/authorization);
    • Authentication only: the step involving the PDP GE may be skipped for some use case;
    • Full authentication and authorization: includes the step involving the PDP GE.
  • Transport-Layer Security support:
    • As a server: for securing communications between clients and the PEP Proxy;
    • As a client: for securing communications between the PEP Proxy and the IdM GE and PDP GE.
  • OAuth Bearer token (RFC 6750) support.

Detailed Specifications

Open API Specification


Re-utilised Technologies/Specifications

The PEP Proxy GE is based on RESTful Design Principles. The technologies and specifications used in this GE are:

  • RESTful web services
  • HTTP/1.1
  • OAuth 2.0
  • JSON and XML data serialization formats.

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-X-800_Link). 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)
  • 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 && 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.
  • Privacy. Dictionary definitions of privacy refer to "the quality or state of being apart from company or observation, seclusion [...] freedom from unauthorized intrusion" (Merriam-Webster online [MerrWebPriv]). In the online world, we rely on a pragmatic definition of privacy, saying that privacy is the state of being free from certain privacy threats.
  • Privacy threats. The fundamental privacy threats are: traceability (the digital traces left during transactions), linkability (profile accumulation based on the digital traces), loss of control (over personal data) and identity theft (impersonation).
  • 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