20120917 fun with rest - plembo/onemoretech GitHub Wiki

title: Fun with REST link: https://onemoretech.wordpress.com/2012/09/17/fun-with-rest/ author: lembobro description: post_id: 3380 created: 2012/09/17 17:18:17 created_gmt: 2012/09/17 21:18:17 comment_status: closed post_name: fun-with-rest status: publish post_type: post

Fun with REST

OpenAM implements a RESTful interface that allows applications to perform a variety of operations directly against the SSO server. Some examples follow.

Note: This post was thoroughly updated on June 10, 2015.

ForgeRock's latest OpenAM 11 release introduced a new RESTful API, while retaining the "legacy" API described below in "deprecated" status. As of the OpenAM 13 snapshot this remains the case, but at this point I'd recommend that anyone interested in using REST with OpenAM should prepare to implement it using the new API. Check out the OpenAM 11 Developer's Guide chapter on Using RESTful Web Services, for more.

These examples use the legacy API and assume a load balanced OpenAM environment with the url:

https://testsso.example.com/openam/

Login

curl --request POST \
--data "username=testuser&password=testpass1" \
http://testsso.example.com/openam/identity/authenticate

If this is successful, the server will return a token like:

token.id=AQIC5wM2LY4SfcwEYIug0Vy8jYWvMvVvybU3QmA_yBJIE0w.*AAJTSQACMDIAAlMxAAIwMQ..*

This token is what is used to perform the "rest" of the operations detailed here. In order to shorten the strings below I'm going to truncate the token text somewhat. Well, actually quite a bit. Don't do this in real life because nothing would work then. See Understanding the iPlanetDirectoryPro Cookie for important information on token internals.

Logout

curl --request POST \
--data "subjectid=AQIC5wM2LY..*"
http://testsso.example.com/openam/identity/logout

The subjectid is in fact the same value as token.id above. Performing this operation invalidates the token.

Validate a Token

curl --request POST \
--data "tokenid=AQIC5wM2LY..*" \
http://testsso.example.com/openam/identity/isTokenValid

Will return "boolean=true" if the token is good. Two notes here: (a) This won't work if you've invalidated the token as in the previous example; (b) The correct syntax is "tokenid", NOT "token.id".

Authorization

curl "http://testsso.example.com/openam/identity/authorize? \
uri=http://www.example.com/test/printenv.php \
&action=GET&subjectid=AQIC5wM2LY..*"

The uri here is a protected target url. Submitting this will cause OpenAM to advise whether the authenticated user is authorized to perform the action specified.

Token Attribute Retrieval

curl --request POST \
--data "subjectid=AQIC5wM2LY..*" \
http://testsso.example.com/openam/identity/attributes

Returns a list of attribute value pairs for the subject whose token is provided. These attributes are specified in the user data sources against which authentication/authorization is made. Of course you'd want to wrap all this up in an SSL conversation, but my developers at work say that's a bit of a challenge. Man, I hope not. Because nothing ruins your day like getting a call from the auditors...