From FIWARE Forge Wiki

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 © 2012-2016 by UPM. All Rights Reserved.
• Copyright © 2012-2014 by NSN.
• Copyright © 2012-2014 by DT.
• Copyright © 2016 by Thales.

Legal Notice

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

Overview

On the one hand, the ever-growing tsunami of today’s shore-bound technologies can often overwhelm the user, significantly affecting his daily life. On a daily basis, he/she is forced to depend on his technological competence. The smooth running of his affairs depends on the user’s ability to handle a whole raft of often transient technologies. On account of very intensive, at times forced usage of the Internet and diverse services, the user encounters the need to transfer his “network-duties” to the networks as much as possible.

In other words, he/she seeks to find a convenient problem solver, which will allow him/her to cope easily and securely with services. Thus, the need arises for a clever composed Identity Management system, which will address the users’ requirements.

Identity Management (IdM) encompasses some aspects involved with users' access to networks, services and applications, including secure and private authentication from users to devices, networks and services, user profile and authorization management, Single Sign-On (SSO) to service domains and Identity Federation towards applications.

An IdM system aims to undertake the complex task of handling the various technologies in the aforementioned security domains, and provide user-friendly technologies, putting the end user and his needs squarely at the centre of the architecture (user-centric approach) whilst protecting his/her privacy.

On the other hand, more and more companies, especially small and medium enterprises are externalizing the identity management part of their applications – mostly web applications - to cloud services, so called IDaaS (Identity management as a Service). Indeed, they prefer to buy (or use for free) such IDaaS solutions rather than develop technology and/or build the infrastructure for something – identity and access management – they have no expertise in.

The Identity Management Enabler itself aims at providing IDaaS and therefore must comply with the requirements of an actual cloud-ready service, such as multi-tenancy, scalability, standard-compliant protocols and APIs, etc. As a result, instead of developing and operating the user and profile management by themselves, developers can have it hosted in the Cloud (e.g. FIWARE Lab) as a specific tenant of the IdM GE, and it will be delivered on demand.

Target usage

This enabler provides authentication, basic authorization and security assertions (such as user attributes) as a service to relying parties. The relying parties are typically service providers that provide easy and secure access to their services to users/IoT/other services for instance by means of SSO and that rely on (personal user) attributes (e.g. preferences, location, home address, etc). The users need easy access (SSO) to the growing number of services, and many of them also prefer their personal/identity attributes to be maintained by a trusted party that also protects the users’ privacy.

The Identity Management Generic Enabler can be used by such a trusted party, which we also call an identity provider (for SSO) and attribute broker. The Identity Management GE is a core Security GE that provides services to its relying parties via open protocols such as OAuth and OASIS SAML v2.0 (Security Assertion Markup Language). Motivated by IoT, the enabler also covers new user attributes such as things – IoT components (e.g. sensors) - owned or used by the user, as well as managing the identity of the things themselves (attributes, current users, location, usage history, etc).

Furthermore, the authentication feature of the enabler also covers the authentication of things to users, services or other things as relying parties; and the authentication of users and services to other things as relying parties. It also supports user SSO across multiple things.

Basic Concepts

We give you short definitions of key terms in the context of the Security Chapter in the Security glossary. We now give you the extended versions of the definitions to improve your understanding of the field before we tackle the next concepts:

• (Digital) Identity: 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. However, for the purpose of this document, the Identity Gang’s definition suits well (cf. http://wiki.idcommons.net/Digital_Identity):
  • A digital identity is “a digital representation of a set of Claims made by one party about itself or another digital subject.”
  • 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.
• (Entity) Authentication: A simple definition is given by RFC 3588: the act of verifying the identity of an entity (subject). In his book Trust In Cyberspace^[1], Fred Schneider adds the concept level of confidence to this definition: 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.
• Credential: A set of data presented as evidence of a claimed Identity and/or entitlements, typically for authentication purposes.
• (Digital) Identity Provider: 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. (WS-Federation specification). The IdM GE can play the role of Identity Provider. It is actually one of its most important roles in FIWARE.
• Relying party (RP): An entity that relies on an identity representation or claim (e.g. security token or assertion) issued by a requesting/asserting entity (e.g. Identity Provider such as the IdM GE) within some request context, typically for authentication purposes.
• Single Sign-On: From a Principal’s [user’s or application’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 [aka Relying Parties in this context] […]. 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).
• Federated Identity Management (aka Federated Identity): Identity management capabilities that allow the users of one enterprise environment (security domain, aka realm) to access the services of another without registering them in the user registries of the other. The WS-Federation specification gives a more formal definition: 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. A practical application of this is federated SSO (Single Sign-On): This allows users registered in one IdM X to authenticate to another IdM Y without being previously registered in the IdM Y, and, as result, to authenticate to all service providers trusting IdM Y. But Federated identity goes beyond that. For instance, it also deals with cross-domain (e.g. between IdM X’s domain and Y’s domain) user account provisioning (just-in-time provisioning), exchange and mapping of user attributes, cross-domain authorization, etc.
• Authorization: Term used interchangeably for two close but distinct meanings depending on the context:
  • Authorization management: Process of assigning permissions to entities. Also known as user-permission assignment. In the context of FIWARE, the IdM GE typically handles that part; therefore the term is used with that meaning in the context of the IdM, unless told otherwise.
  • Authorization enforcement: Process of determining whether an entity should be allowed to do something whenever the entity requests access, followed by the actual granting of access or not. In the context of FIWARE, the Authorization PDP GE determines whether access should be allowed, and based on this PDP’s decision, the PEP Proxy GE actually grants or denies the requested access to the requesting entity. See the Authorization PDP GE (§3.2) and PEP Proxy GE (§ 3.3) sections for more information.

The next sections describe the higher-level concepts supporting the aforementioned features.

User Life-Cycle Management

The IdM offers tools for administrators to support the handling of user life-cycle functions. It reduces the effort for account creation and management, as it supports the enforcement of policies and procedures for user identity lifecycle management: user registration, user profile update, user profile removal. Administrators can quickly configure customized pages for the inclusion of different authentication providers, registration of tenant applications with access to user profile data and the handling of error notifications. For end users, the IdM provides a convenient solution for registering with applications since it gives them a means to re-use attributes like address, email or others, thus allowing an easy and convenient management of profile information. Users and administrators can rely on standardized solutions to allow user self-service features like:

• User registration/unregistration and login/logout,
• Checks for password strength,
• Password reset or renewal procedures or
• Secured storage of user data.

Flexible Authentication Providers

In addition to providing a native login, the Identity Provider (IdP) supports the integration of multiple 3rd party authentication providers. Foremost, it supports in a first step the configuration of preferred identity providers to lower entry barriers for a native user registration to administrators and on user side to link a preferred 3rd party IdP as alternative authentication provider to a native account. For instance, using the SAML protocol, you can trust external SAML-compliant IdPs to authenticate the users. Once the user is authenticated by a trusted external IdP, i.e. he was issued a valid SAML token, the trusting IdP is able to validate that SAML token because it is signed by a trusted IdP, and therefore authenticates the user. In this process, you can see that the user did not need to register with the trusting IdP, therefore saving a lot of registration procedures.

Third-Party Login

3rd party login supports customers of the IdM to enhance the reach of their websites by means of attracting users without forcing them to register new user accounts on their sites manually. 3rd party login allows users to register to the customers’ sites with already existing digital identities from their favorite 3rd party identity providers, such as Google, Facebook or Yahoo. Thus, 3rd party login lowers the obstacles of registration processes and increases the number of successful business flows on the customers’ sites.

Web Single Sign-On

As it is possible to configure several applications that shall be linked to his IdM, the main benefit for users is a single sign-on (SSO) to all these applications.

Hosted User Profile Management

The IdM offers hosted user profile storage with specific user profile attributes. Applications do not have to run and manage their own persistent user data storages, but instead can use the IdM user profile storage as a SaaS (Software as a Service) offering.

Multi-Tenancy

A multi-tenancy architecture refers to a principle in software architecture where a single software instance runs on a server, serving multiple client/customer organizations (tenants). Multi-tenancy contrasts with a multi-instance architecture where separate and dedicated software instances (or hardware systems) are set up for different client organizations. With a multi-tenant architecture, a software application is designed to virtually partition its data and configuration, and each client organization works with a customized virtual application instance. In a multi-tenancy environment, multiple customers share the same application, running on the same operating system, on the same virtualized hardware, with the same data storage mechanism. The distinction between the customers is achieved during application design, thus customers do not share or see each other's data. The concept allows each tenant to apply their own branding to login or registration UIs or for user self-services to create a user experience that is aligned with the one offered in a tenant application.

Main Interactions

We here define the mandatory and optional interfaces, including API and protocol standards, expected from IdM GE implementations; also who interacts with these interfaces, and possible interactions.

High-level IdM GE Architecture

This section provides an overview of the Identity Management Generic Enabler (IdM GE)’s interfaces. The general structure of a FIWARE IdM GE is sketched in the following figure:

Identity Management GE - High Level Architecture

The various modules and interactions shown on the figure are described in the next sections.

User interfaces

• End User portal: This is where end users self-register in the IdM with email address, password, etc. This is typically implemented as a Web user interface. End users may also review and modify their personal account data and maintain their privacy settings using this portal.
• Application Developer Portal: This is where developers can register and manage their applications, especially the client applications, including the application credentials. With such credentials, the application is able to authenticate to the IdM and participate in an authentication and authorization process (explained in more details in the #Authentication_and_Authorization_interfaces later on) to get access to a protected Service Provider. The developer can also manage access for his application, and in particular, define application-specific roles.

Management APIs

• User management API: Provides a REST API to create user accounts, retrieve and modify user attributes, delete user accounts. The interface must be compliant with SCIM 2.0^[2] REST API. The user management API is typically used by web applications (or any kind of service provider), to retrieve extra information about their users.
• Application management API: REST API for managing applications (registering the application, retrieving and modifying application data such as credentials, deleting the application).
• Access Management API: REST API to manage roles globally or for a specific application. There are two aspects of role management involved here: defining the role permissions and assigning the roles to the users. The role permissions make up an authorization policy that may be pushed to the Authorization PDP GE via its PAP API. Please refer to Basic Concepts section of the Authorization PDP GE architecture description for more information.

Authentication and Authorization Interfaces

This section focuses on the standards used and made mandatory for the IdM GE’s Authentication and Authorization interfaces, and SSO by extension, with the help of message flows and reference code examples, thus offering an easy implementation and usage of the Generic Enabler.

SAML

The Identity Management GE supports SAML 2.0^[3] to provide federated identity, more specifically federated Single Sign-On and user attribute exchange between IdM systems (FIWARE IdM GE and other Identity Providers).

The advantages of SAML 2.0 are:

• Provides a means of exchanging data between security domains (i.e. the Identity Management GE and its federated service providers (relying parties))
• Provides the SSO feature for the federated service providers to the Users
• Service providers do not need to authenticate users themselves
• Provides security features such as digital signatures to certify the integrity of the exchanged data (and certified attributes)
• Standardized, non-proprietary protocol (e.g. also supported by Google)

The diagram below shows an example of a SAML interaction. Details of the request parameters and flows can be found in the SAML specification^[3]. On the picture, the SAML IDM may be in fact the IdM GE in the context of FIWARE or another SAML Identity Provider that is federated with the FIWARE IdM GE.

Identity Management GE - SAML Authentication Flow

Authentication Request

In a SAML Web-SSO flow, whenever the user requests access to a service provider (Relying Party in the previous figure) for the first time or after his/her session cookie for this service has expired, in other words, with no valid session cookie, the service redirects the user - the user agent (typically the web navigator) - to a trusted Identity Provider (SAML IDM on the previous figure) with the following SAML authentication request. The main parameters are the time when the request is emitted (Issue Instant) and the service identifier as known by the IDM, so that the IDM knows, which relying party the user is requesting a SAML token for; and therefore, where to redirect the user after authentication, which cryptographic protection to apply on the SAML token, which SAML attributes to include in the token, and so on. Please see an example of such Request below.

Authentication Response

The user authenticates to the SAML IDM, and after successful authentication, the SAML IDM returns a SAML Authentication Response that contains the SAML assertion (aka SAML token) signed by the IDM. Besides the digital signature, it contains various statements, such as the time when it was issued, the IDM identifier, the validity period, the Relying Party for which this token may be used, the method of authentication used to obtain the token, etc. Please see an example below.

The IDM redirects the user with this Response to the Relying Party, i.e. the service provider. The latter considers the user is properly authenticated because the SAML token received from the user is signed and issued by a trusted IDM; and the token proves that the user has successfully authenticated to this IDM.

OAuth2

The OAuth^[4] standard is an authentication and authorization framework that initially addresses the scenario where you have to allow a website or application (Consumer) to access protected resources of an End User from a web service (Service Provider) via an API, without requiring this End User to disclose their Service Provider credentials to the Consumer. Then the standard was extended in its version 2.0 to address other more traditional use cases of web API authentication, in order to use the same framework for most common scenarios in this domain. We now dare to say that OAuth creates a generic methodology for web – especially RESTful – API authentication.

We use the term Service Provider here as an equivalent for the term Resource Server used in the RFC of OAuth 2.0^[4] mentioned above, because we think it makes more sense to FIWARE developers with regards to what the IdM GE’s OAuth capabilities can do for him/her. The term Resource Server may sound more restrictive in terms of possible use cases than OAuth actually addresses. For the record, OAuth 1.0 used the term Service Provider instead as well. The same comment goes for Consumer, as in Service Consumer, used here instead of the term Client in the OAuth 2.0^[4] specification.

OAuth 2.0 presents significant advantages compared to other delegation/authorization frameworks:

• A standardized protocol supported by a wider set of Service Providers (Facebook, Google, LinkedIn…)
• The end user grants access for a consumer to a specific resource by providing an access token to the consumer. The user may be offline, when the consumer accesses the resource, i.e. actually makes use of the access token.
• The end user is in full control of who can access his/her resources. The delegation of access can be limited in scope and time, and may be revoked any time by the user.
• Mitigation of security risks of sharing credentials with third party: Indeed, if not using OAuth, for the same kind of requirement, the third party application (Consumer) gives no choice to the user but to give away their credentials to the third party, with the associated risks listed below:
  • The third party (Consumer) is now storing the end user’s credentials. In particular, it needs access to the user’s password in clear text in order to authenticate on his behalf to the Service Provider. This is different from the Service Provider’s side, where only a hash of the password is needed for authenticating the user. As a result, if the third party is compromised, so are your credentials.
  • This solution works well for password authentication only. It is not compatible with other forms of authentication, more complex, such as the ones relying on a hardware device and/or biometrics.
  • The third party gets the same access as you, i.e. unlimited access to all your resources on the Service Provider.
  • Revocation of the third party’s access by the user is painful, because it requires a change of password. But then it removes access from every other third party, which was not intended. Therefore, you have to go find and replace the password with the new one for all these other third parties that you still want to grant access to. In other words, the access revocation cannot be done for a specific third party and only this one.
• Different grant types for different scenarios:
  • Authorization Code grant: The most well-known when people think of OAuth, used whenever you log on some website with the Facebook/Twitter/Google login button. For example, if you click on the Google button on the website X (Consumer), you are redirected to Google (OAuth server) for sign-in, then asked if website X can access your Google name, email address, etc. (your resources at Google). If you say yes, you are redirected to website X with a special token called authorization code. Then the website X authenticates to Google (OAuth server) and then exchanges the authorization code for the actual access token, in the background, without the end-user being involved; and uses this access token to get user info from Google API (Service Provider). This process is explained in further details in the next section. You cannot fail to notice that in this example, the OAuth server and Service Provider are both Google’s. However, in FIWARE, the Service Provider may be completely distinct from the IdM GE that plays the role of the OAuth Server, i.e. not owned by the same organization at all.
  • Implicit grant: This is similar to the Authorization code grant, except the access token is returned to the Consumer right away, when the user is redirected back, instead of the authorization code. Therefore, the step where the Consumer authenticates to the OAuth server is skipped. As a result, the authorization flow is simpler and the Consumer does not need to store its credentials for authenticating itself to the OAuth server at all. This is particularly useful for lightweight applications such as JavaScript embedded in the browser that are not capable of storing/persisting secret credentials.
  • Resource owner credentials grant: this is the old traditional way described previously in the Mitigation of security risks of sharing credentials with third party, where the Consumer asks the username and password of the end user (Resource Owner in OAuth2 terms). This is only suitable for trusted clients such as the user’s own mobile phone or PC. It can be used for other specific use cases such as legacy applications for which implementing the authorization code grant requires too much effort, but then you should be perfectly aware of the security implications mentioned earlier and in the OAuth specification.
  • Client credentials grant: similar to the Resource owner credentials grant, except the Consumer (i.e. Client in OAuth 2 terms) does not ask for the user’s credentials, but uses its own. In other words, this addresses the traditional client-server authentication scenario where the client authenticates to the server (OAuth server in this case) on its own (with its own credentials). In the context of OAuth, the client gets an access token for the particular Service Provider specified in the authentication request, as a result.

Implementations of this GE must support at least the authorization code grant (§4.1 of OAuth 2.0^[4] specification) and resource owner password credentials grant (§4.3 of OAuth 2.0^[4] specification). Optionally implicit grant (§4.2 of OAuth 2.0^[4] specification) may also be supported. IDM GEis should also allow configuring trusted FIWARE components to access protected resources using (§4.4 of OAuth 2.0^[4] specification) client credentials grant.

Below it is shown an example of OAuth2 interaction for the Authorization Code grant, already summarized in the previous paragraph. Details of the request parameters and flows can be found in the protocol specification^[4]. In the context of FIWARE, the OAuth Server role shown on the picture is played by the IdM GE.

Identity Management GE - OAuth 2.0 Authentication Flow

Get Request Token

https://api.login.<xyz.com>/oauth/v2/get_request_token?oauth_nonce=ce2130523f788f313f76314ed3965ea6
&oauth_timestamp=1202956957
&oauth_consumer_key=123456891011121314151617181920
&oauth_signature_method=plaintext
&oauth_signature=abcdef
&oauth_version=1.0
&xoauth_lang_pref="en-us"
&oauth_callback="http://yoursite.com/callback"

Get Request Token Response

oauth_token=z4ezdgj
&oauth_token_secret=47ba47e0048b7f2105db67df18ffd24bd072688a
&oauth_expires_in=3600
&xoauth_request_auth_url=https%3A%2F%2Fapi.login.<xyz.com>%2Foauth%2Fv2%2Frequest_auth%3Foauth_token%3Dz4ezdgj
&oauth_callback_confirmed=true      

Get Access Token Request

https://api.login.<xyz.com>/oauth/v2/request_auth?oauth_token=j5nyp6

Get Access Token Response

http://yoursite.com/callback?oauth_verifierer=svmhhd

Exchange Token Request

https://api.login.<xyz.com>/oauth/v2/get_token?oauth_consumer_key=dj0yJmk9NG5USlVvTlZsZEpnJmQ9WVdrOVQwa
zFPRUozTkc4bWNHozlNVE13TXprM01UUTBNZy0tJnM9Y29uc3VtZXJzZWNyZXQmeD1kNg--

&oauth_signature_method=PLAINTEXT

&oauth_version=1.0

&oauth_verifier=svmhhd

&oauth_token=gugucz&oauth_timestamp=1228169662

&oauth_nonce=8B9SpF

&oauth_signature=5f78507cf0acc38890cf5aa697210822e90c8b1c%261fa61b464613d0d32de80089fe099caf34c9dac5      

Exchange Token Response

oauth_token=A%3DqVDHXBngo1tEtzox.JMhzd91Rk99.39Al7hos3J80mm1j_3nGP4BiilL777vUj2rsPLj1cZw.srbisvw.cz42Lzmlxt
H0Kk9mkXilvS1ll5lNoMKXO5zy5YG4vO3fbGKewp7IESYMIdEi4Md7SroYiv6kBCEjqB4jXr0.8XsMvOlQgZ.aKNKXwc2sv3n4BOZxs
54tzXV6rGNpEHZUaj9CovPUo44isTgs9FnLIKpXFCU4Jq1BB3_IOTFBNf1vtf5vSxaxe_L5dUhr.i15Hx0LTZ2tlsWeDcActSGGBWVc
vytPF3cK9mDWy44baBgCVI3AEbGCqg.NGhDPqOh1ZHfKFtYlBZfG4xf2n..CdxcM5x4INxnVz2.biMkfhfkw8haJuR0RaUY37lBxZ9z          

Username/Password

Besides the authentication/authorization mechanisms described above, the basic username/password authentication method is supported. The username and password are verified against the IdM's backend user database.

Identity Management GE infrastructure

Beyond the modules and main interactions with other GEs and components described in the previous sections, the IdM GE may depend on additional security components to secure access to the GE interfaces. For example, the IdM GE requires a Public Key Infrastructure (PKI) to issue and manage SSL certificates for transport-level security (authentication, confidentiality and integrity) of communications with the IdM (e.g. over HTTPS), and message-level security such as digital signatures of SAML assertions issued by the IdM.

The IdM GE may also depend on non-security components such as a mail server to communicate with the users (e.g. for email address confirmation, password recovery...).

References

1. ↑ F. Schneider, Trust in Cyberspace, 1998. Trust in Cyberspace. National Academy Press, Washington, DC, USA. 1998.
2. ↑ System for Cross-Domain Identity Management - http://tools.ietf.org/html/draft-ietf-scim-core-schema-02 and http://tools.ietf.org/html/draft-ietf-scim-api-02
3. ↑ ^{3.0 3.1} Security Assertion Markup Language - http://saml.xml.org/saml-specifications, http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security#samlv20
4. ↑ ^{4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7} IETF RFC 6749 - https://tools.ietf.org/html/rfc6749, http://oauth.net

Detailed Specifications

The detailed API specification is available on the APIary website: http://docs.keyrock.apiary.io/

Re-utilised Technologies/Specifications

The Identity Management GEis are based on the following technologies:

• SAML 2.0 protocol ,
• RFC 6749 - The OAuth 2.0 Authorization Framework,
• SCIM protocol .

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