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.
These examples use the legacy API and assume a load balanced OpenAM environment with the url:
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:
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.
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”.
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…