Month: May 2010

Using the REST API for Identity Management

It’s not that well known, but OpenAM has a REST interface for login/logging/authorization and also for basic identity Management too. This post will describe the IDM functionality of the REST API, so it’s about creating, updating and deleting users in the DataStores.

When you google the term ‘OpenAM REST’, you won’t find much thing, because it’s not really well documented part of OpenAM, but if you google hard enough you will find this link to Docteger’s blog. This post is just GREAT, everything in one place, but it’s missing the answer for the ‘how-can-I-handle-realms-with-this’ type of question. So here is my result of few hours reading of IdentityServicesImpl:

Create Identity

https://<FQDNSSO>/openam/identity/create?identity_name=username&identity_realm=/&
identity_type=user&identity_attribute_names=cn&identity_attribute_values_cn=
MyNewCn&identity_attribute_names=userPassword&
identity_attribute_values_userPassword=password

Gotcha #1:
The password length needs to be at least 8 characters by default, if you want to change this, read this mail.

Read Identity

https://<FQDNSSO>/openam/identity/read?name=username&attributes_names=realm&
attributes_values_realm=/

Tip #1:
You could use the attributes_names parameter to ask specific parameters of the given identity.

Update Identity

https://<FQDNSSO>/openam/identity/update?identity_name=username&identity_realm=/&
identity_attribute_names=cn&identity_attribute_values_cn=NewerCn

Here you only have to add the parameters to the query, which are actually changed.
Gotcha #2:
If you want to change the password like this, then you need an authenticated admin token, since the user can’t (always?) update it’s own password.

Delete Identity

https://<FQDNSSO>/openam/identity/delete?identity_name=username&identity_realm=/&
identity_type=user

Gotcha #3:
There’s no really Gotcha here, you just have to specify, that the deletable item is actually a user.

Conclusion

This is great and everything, but you can’t do these stuff without login & search the user, so here are these calls too:

Authenticate

https://<FQDNSSO>/openam/identity/authenticate?username=username&
password=password&uri=realm%3D/%26service%3DldapService

Gotcha #4:
Note the %3D (‘=’) and %26 (‘&’) characters, they are url-encoded, since it’s a single value for the ‘uri’ param.

Search Identity

https://<FQDNSSO>/openam/identity/search?filter=*)(|(inetUserStatus=Active)&
attributes_names=realm&attributes_values_realm=/

Tip #2:
You can use the filter with some dirty hack to give OR filters too as the previous URL shows.

Summary

The REST interface is great and FAST, so use it whenever you have the chance. The only problem with it this weird parameter-handling, one time it’s ‘identity_name’, another time it’s ‘username’, so you probably going to need a few parser for using it, but I think it’s worth it. If I heard right, it’s going to use JSON-format parameters in the future, so it’s going to be much better. 🙂

It’s aliiive

Welcome!

Thanks to the help of Jonathan, I have a ForgeRock Blog, yuppee. 🙂
In the next few days I will try to create an article-serie about authentication module development, but this won’t be a short one, so it’ll may took a while. Until I figure out the structure of this article, I post about other, small tips for OpenAM, so stay tuned!