onsdag 20 november 2013

ForgeRock Common REST API overview

One of the unique features of the ForgeRock Open Identity Stack, is that all components of the stack share a single, easy to use RESTful web API. REST stands for Representational State Transfer and is a technique that relies on stateless, client-server and cacheable communication where the HTTP protocol is used. Not only is REST a more lightweight alternative to traditional SOAP based web services but given its HTTP nature, makes it easy to use in a firewall controlled environment.

The Open Identity Stack contains three different products, each with individual modules and capabilities; OpenAM, OpenDJ and OpenIDM. The Common REST or CREST can be used to access and leverage all the underlying modules and features with a set of easy to remember REST calls (CRUDPAQ).

Add a resource that does not yet exist
Modify part of an existing resource
Retrieve a single resource
Perform a predefined action
Replace an existing resource
List a set of resources
Remove an existing resource

OpenAM offers a RESTful API for authentication, logout, cookie information, token attribute retrieval and token validation, authorization, OAuth 2.0 Authorization, OpenID Connecto 1.0, self-registration, password management, managing identities, managing realms and logging.

The present implementation in OpenDJ maps JSON resources onto LDAP entries, meaning REST clients can in principle do just about anything an LDAP client can do with directory data.

OpenIDM provides an implementation that allows you to manipulate managed objects as well as system objects.

Interacting with the RESTful API
There are a number of ways and programming languages which you can easily interact with the ForgeRock Common REST API. An easy way to invoke REST calls is to get hold of a REST client that allows you to easily provide the necessary details, save calls and tweak them as you play with the interface. One REST client that often is being referred to in our documentation is CURL (http://curl.haxx.se). CURL is a command line tool for submitting data with URL syntax and free to use.

Some samples using ForgeRock Common REST

Lets retrieve a user from OpenDJ, authenticated as Stevie with password Wonder.

$ curl
--request GET
--user stevie:wonder
 "_rev" : "000000005b337348",
 "schemas" : [ "urn:scim:schemas:core:1.0" ],
 "contactInformation" : {
   "telephoneNumber" : "+1 408 555 1212",
   "emailAddress" : "newuser@example.com"
 "_id" : "newuser",
 "name" : {
   "familyName" : "New",
   "givenName" : "User"
 "userName" : "newuser@example.com",
 "displayName" : "New User",
 "meta" : {
   "created" : "2013-04-11T09:58:27Z"
 "manager" : [ {
   "_id" : "opope",
   "displayName" : "Olivia Pope”
 } ]

In OpenIDM we can simply create a new user using

$ curl --header "Content-Type: application/json"
--header "X-OpenIDM-Username: openidm-admin"
--header "X-OpenIDM-Password: openidm-admin"
--request PUT --data '{ "userName":"joe", "givenName":"joe", "familyName":"smith", "email":"joe@example.com", "phoneNumber":"555-123-1234", "password":"TestPassw0rd", "description":"My first user" }' http://localhost:8080/openidm/managed/user/joe

In OpenAM we can perform an authentication with the following call:

$ curl --request POST
--header "X-OpenAM-Username: demo" --header "X-OpenAM-Password: changeit"
--header "Content-Type: application/json" --data "{}"
{ "tokenId": "AQIC5w...NTcy*", "successUrl": "/openam/console" }

The above are just three simple calls to showcase the easy of use and flexibility of the Common REST API the Open Identity Stack offers. Check out the suggested reading links for more samples and information on how to leverage the capabilities exposed by the API.

Suggested reading



Inga kommentarer:

Skicka en kommentar