ForgeRock Blog

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, it is 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).

 

Create

Add a resource that does not yet exist          .

Patch

Modify part of an existing resource

Read

Retrieve a single resource

Action

Perform a predefined action

Update

Replace an existing resource

Query

List a set of resources

Delete

Remove an existing resource

.

OpenAM

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

OpenDJ

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

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 with which you can easily interact with the ForgeRock Common REST API. An easy way to invoke REST calls is to get a 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 we often refer to in our documentation is CURL (http://curl.haxx.se). CURL is a command line tool for submitting data with URL syntax and is free to use.

.

Some examples using ForgeRock Common REST

Let’s retrieve a user from OpenDJ, authenticated as Stevie with password Wonder.


$ curl

–request GET

–user stevie:wonder

http://opendj.example.com:8080/users/newuser?_prettyPrint=true

{

 “_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” : “kvaughan”,

   “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 “{}”

https://openam.example.com:8443/openam/json/authenticate

{ “tokenId”: “AQIC5w…NTcy*”, “successUrl”: “/openam/console” }


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

.

Suggested reading

OpenAM: http://docs.forgerock.org/en/openam/11.0.0/dev-guide/#chap-rest

OpenIDM: http://docs.forgerock.org/en/openidm/2.0.3/integrators-guide/index.html#appendix-rest

OpenDJ: http://docs.forgerock.org/en/opendj/2.6.0/admin-guide/#chap-rest-operations

Comments are closed.