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
Identity Management Generic Enabler API Specification - FIWARE Forge Wiki

Identity Management Generic Enabler API Specification

From FIWARE Forge Wiki

Jump to: navigation, search


Introduction to the Identity Management GE (IdM GE) API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.


IdM GE API specifications comply with existing standards for authentication and user and provide access information. The following sections provide pointers to those standards and, when applicable, details about how the RESTful binding work.

Intended Audience

This specification is intended for Service Consumers (with developement skills) and Cloud Providers. For the former, this document provides a full specification of how to interoperate with the Identity Management Service API. For the latter, this specification indicates the interface to be provided to the client application developers to provide the described functionalities. To use this information, the reader should first have a general understanding of the Generic Enabler service (FIWARE.ArchitectureDescription.Identity_Management_Generic_Enabler).

The API user should be familiar with:

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

API Change History

Current version is: Version 2.0.0, 2013.10.18.

The most recent changes are described in the table below:

Revision Date Changes Summary
  • First version of the Identity Management API Specification
  • Revision and enhancement reflecting actual development

How to Read this Document

The following list summarizes special notations for the current and future versions of this document.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g. URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.

Additional Resources

Detailed specification and descriptions can be found here:

  • SAML
  • OAuth
  • SCIM
  • Some examples are provided in:

A detailed description of what parts of the used standards is considered as optional or mandatory is described in the Open Specification.

General Identity Management Generic Enabler API Information

Resources Summary

An IdM GE have to exporte the following REST APIs:

  • REST API for resources access:
  • Tokens
  • Projects
  • Users
  • Roles
  • Consumers
  • More info regarding the REST API here
  • OAuth2
  • More info regarding OAuth2 API here
  • SCIM 2.0
  • Users
  • Groups
  • Service Provider


At service side one of the herein specified authentication protocols (SAML, OAuth2) must be implemented.

Representation Format

In case of SAML, XML is used as representation format. SCIM uses JSON structured responses with UTF-8 encoding. For OAuth2, no such format is defined.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

The resources are uniquely identified by their URI.


Resources are only limited by hardware resources.


The SAML protocol supports extensions, however this is not supported at the moment. Maybe this will be considered in the future.

GET /extensionsList of all available extensions


Synchronous Faults

  • SAML2.0:

SAML always returns a SAML response containing the field "Status" defined in the SAML specification:


In case of an error, the status code will be "Error" instead of "Success" and a detailed error message may be contained within the status block.

  • OAuth2.0:
Response CodeDescription
HTTP 400 Bad Request
HTTP 401 Unauthorized
HTTP 403 Forbidden
HTTP 500 Internal Error
HTTP 501 Unsupported HTTP Method

  • SCIM2.0:
SCIM will respond with standard HTTP error messages identical to the OAuth2.0 case above

Example Identity Management GE implementations

  • KeyRock: authorisation using OAuth 2.0, cross-domain identity management using SCIM 2.0

Please refer also to the User and Programmers Guides:

Personal tools
Create a book