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. 🙂

14 comments

  1. Hi, great article.

    Do you know if you can add a user to a group on CREATE or UPDATE?

    also, do you know if you can retrieve the ENTRYUUID value via a READ or SEARCH or any other method in fact?

    Dwiamo

  2. With setting the uniqueMember attribute on the group you should be able to do so. Reading operational attributes can be tricky, and I’m not sure it will work all of the time, but if you add the entryUUID attribute on the Datastore configuration page LDAP User attributes section, it can actually work.

  3. Thanks for the quick response. I will try the Datastore Config for EntryUUID and feedback my results.

    I have just tried the uniqueMember suggestion but no luck I have executed it in the following way.

    curl -d “identity_name=restapi3&identity_attribute_names=userpassword&identity_attribute_values_userpassword=password&iattribute_names=uniqueMember&identity_attribute_values_uniqueMember=testgroup&identity_realm=/&identity_type=user&admin=AQIC5wM2LY4SfczMvVN1fjnk2Iv2/Vo0gpe3oENKCWkSVow=@AAJTSQACMDE=#” http://localhost:8081/openam/identity/create

    Perhaps i have misunderstood?

  4. Uniquemember attribute only exists for groups, if you want to store membership information for user, then you should try to set the memberOf attribute instead (after registering in the datastore config).

  5. ok understood and many thanks

    one last question, is it possible to apply a template to be used with a CREATE? i.e. when the user is created it is done so to a template that includes the groups etc – based on specific template attribute or even based on

  6. Is there any documentation anywhere for the filter syntax and the other crazy hacks? E.g., I can get filter=*)(|(sn=Somename) to work, but have had no luck with some other seemingly valid LDAP filter strings — particularly “memberOf”.

  7. Hi aldaris,
    can you help me with something?
    i’m trying to delete a user using the REST API but i keep getting this error
    Estado HTTP 500 – exception.name=com.sun.identity.idsvcs.GeneralFailure Permission to perform the read operation denied to id=fbotero,ou=user,dc=opensso,dc=java,dc=net

    type Informe de estado

    mensaje exception.name=com.sun.identity.idsvcs.GeneralFailure Permission to perform the read operation denied to id=fbotero,ou=user,dc=opensso,dc=java,dc=net

    descripción El servidor encontró un error interno (exception.name=com.sun.identity.idsvcs.GeneralFailure Permission to perform the read operation denied to id=fbotero,ou=user,dc=opensso,dc=java,dc=net ) que hizo que no pudiera rellenar este requerimiento.

    Apache Tomcat/7.0.14

    where do i give delete privileges to an user?
    Thanks
    Felipe

  8. Hi,

    Need help in retrieving members of a group.

    I created a group named “g1” and add two users “u1” and “u2”.

    How do i perform a read operation on a group to know about the users in the group.

    Mohan

  9. REST API
    Is there a way to add a user to a group without also having to add all previous members of the group? When using the update function it seems to delete all the previous members. If the group is huge, it creates a problem on how to add another member to the group in a scalable way?

  10. You can add users from the other end, update a user entry (identity_type=user) using the identity_group parameter, but there you have to list the groups then. 😉

  11. Do you know if you can add a user to a group on CREATE or UPDATE?

    I done like below,but it’s not added the user to a group,
    plz help me.

    http://wisw0013.nousinfo.com:8080/openam/identity/create?
    admin=AQIC5wM2LY4Sfcw5unUiDhhL-eUTqbStOa2hoOqig1xnSzU.*AAJTSQACMDE.*
    &identity_name=testuser
    &identity_attribute_names=memberOf
    &identity_attribute_values_memberOf=deniedGroup

    http://wisw0013.nousinfo.com:8080/openam/identity/update?
    admin=AQIC5wM2LY4SfcwsKs5mjR3WyKiMLP0uewdwid-EygiJx2c.*AAJTSQACMDE.*
    &identity_name=testuser
    &identity_group=deniedGroup
    &identity_attribute_names=mail
    &identity_attribute_values_mail=testuser%40example.com
    &identity_realm=%2F
    &identity_type=user

Join the Conversation

Your email address will not be published. Required fields are marked *