OpenAM: New REST APIs

OpenAM Community Logo If you have been following the development of OpenAM, you know that OpenAM offers new REST APIs, built on the same underlying CRUDPAQ model used in OpenDJ (and now in the latest builds of OpenIDM as well).

Over time the new REST APIs will replace the old REST APIs, providing more uniform design and responses for modern web client applications, and providing additional access. A table in the draft release notes lists which new URIs are taking over from the old.

You access the new APIs under /json where you deployed OpenAM (for example, http://openam.example.com:8080/openam/json):

  • /json/agents — CRUD and query for policy agent profiles
  • /json/authenticate — Authenticate (including callbacks, modules, chains, etc.)
  • /json/dashboard — Read cloud dashboard profiles
  • /json/groups — CRUD and query for OpenAM groups
  • /json/realms — CRUD for OpenAM realms
  • /json/serverinfo/cookieDomains — Get cookie domains that the server supports
  • /json/sessions?_action=logout — Log a user out based on SSO Token
  • /json/users — CRUD and query for user profiles
  • /json/users?_action=forgotPassword — Help users reset forgotten passwords
  • /json/users?_action=register — Help new users sign up

You can find a load of examples in the chapter on Using RESTful Web Services.

It all starts with authentication. Although the new OpenAM REST API for authentication also lets you do callback-based authentication to take advantage of auth modules that do something other than username/password-based authentication, a simple way to get a token ID is to use zero page login.

$ curl --request POST \
 --header "X-OpenAM-Username: demo" \
 --header "X-OpenAM-Password: changeit" \
 --header "Content-Type: application/json" \
 http://openam.example.com:8080/openam/json/authenticate
{
  "tokenId": "AQIC5wM2LY4SfcwyCO2rILBLpB93G7k4yHM-NN9OJL5zqEU.*AAJTSQACMDEAAlNLABQtMjU0NTQwOTU4Mjg0MTA2MDYyOA..*",
  "successUrl": "/openam/console"
}

The JSON you get back, pretty-printed here, shows the tokenId that corresponds to the user session. The successUrl is the URI to which the user would normally be redirected.

Once you have authenticated, then you can use the tokenId to access other resources. For example, you can read attributes of your user profile.

$ curl --header "iPlanetDirectoryPro: AQIC5wM2LY4SfcwyCO2rILBLpB93G7k4yHM-NN9OJL5zqEU.*AAJTSQACMDEAAlNLABQtMjU0NTQwOTU4Mjg0MTA2MDYyOA..*" \
 http://openam.example.com:8080/openam/json/users/demo?_prettyPrint=true&_fields=realm,uid,sn,cn,inetuserstatus
{
  "realm" : "/",
  "uid" : [ "demo" ],
  "sn" : [ "demo" ],
  "cn" : [ "demo" ],
  "inetuserstatus" : [ "Active" ]
}

After you are done, you can logout.

$ curl --request POST \
 --header "iPlanetDirectoryPro: AQIC5wM2LY4SfcwyCO2rILBLpB93G7k4yHM-NN9OJL5zqEU.*AAJTSQACMDEAAlNLABQtMjU0NTQwOTU4Mjg0MTA2MDYyOA..*" \
 http://openam.example.com:8080/openam/json/sessions?_action=logout
{"result":"Successfully logged out"}

This post only starts to scratch the surface. There really are lots of possibilities. See the chapter, Using RESTful Web Services, for more.

Advertisements

3 thoughts on “OpenAM: New REST APIs

  1. Hi Mark, do you have an example of using the authentication endpoint with callbacks and a specific authentication module? I’m having a hard time understanding the authid: ….jwt-value…. input in the request. Where does that come from?

  2. HI Mike,

    How can I find Openam web policy Agent version from Profile ..
    I have say 500 plus profile for apache and IIS and now I want to find out
    which policy are using which agent version ..

    can you tell be what will the way .. any script ?

    Rgds..HeM

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s