OpenIDM 3.1.0 restful APIs - how to

Supported Operations: Create,Read,Update,Delete,Action and Query

URI for accessing a managed objects: /openidm/managed/type/id

Example: /openidm/managed/user/?_queryId=query-all-ids

URI for accessing system objects: /openidm/system/resource-name/type/id

Example :  /openidm/system/ad/__ACCOUNT__/?_queryId=query-all-ids

As part of the http request the following headers need to be added for the authentication:

X-OpenIDM-Username  - This will be the user name configured in open-idm

X-OpenIDM-Password - This is the password

Create:

Http Type : POST

URI: /openidm/managed/user/?_action=create

Headers:

Body:

Output:

**Note: You can also create objects using HTTP PUT. Also you can pass the _id value incase you don't want to generate the random UUID.  Here are the request details:

URI: /openidm/managed/user/mike123

Headers:

Body:

Output:

Read - Query:

HTTP Type: GET

URI: /openidm/managed/user/?_queryId=query-all-ids

Headers:

Output:

QueryFilter:

For equal to:

URI: /openidm/managed/user/?_queryFilter=userName+eq+"vishnuindla"&_fields=userName,givenName,sn,mail

For starts with:

URI:

URI: /openidm/managed/user/?_queryFilter=userName+sw+"vishnu"&_fields=userName,givenName,sn,mail

Headers:

Output:

Update:

Http Type:  PUT

URI: /openidm/managed/user/0bffb692-5881-4bd0-abd5-edb1e4fc23e3

Headers:

Body:

Output:

Delete:

HTTP Type: DELETE

URI: /openidm/managed/user/8476d76e-a09c-4223-877d-965a686491c8

Headers:

Body:

 Output:

OAM - OIM Integration Password Management

Out-of-the-box self service password management feature of OIM can be used if OAM-OIM integration is enabled. One of the key factors necessary for enabling OAM-OIM integration is that LDAP sync should be enabled in OIM.

OAM-OIM integration process extends the user schema in LDAP. The list of attributes and object classes which are added to schema can be found in IAM_HOME/oam/server/oim-intg/ldif/ojd/schema/ojd_user_schema_add.ldif (This is OUD specific LDIF file).
In OAM, this enablement process also sets the flag "IdentityServiceEnabled" in oam-config.xml to "true".

When a user is created in OIM (through API or console), it gets synched to LDAP (OUD for an instance) with new attributes. The value for couple of attributes are set at the time of user creation, for example: obpasswordchangeflag is set to true. This flag is also set to true when resetPassword API in OIM.

In an OAM-OIM integrated environment when a user tries to authenticate to an application protected by OAM (which uses OUD for user authentication), OAM checks for couple of attributes. Based on these attributes OAM will redirect the user to URLs which are configured in oam-config.xml.

1. If obpasswordchangeflag is true, then user will be redirected to the URL configured for “ForcedPasswordChangeURL” attribute in oam-config.xml.
2. If user has tried multiple times with invalid credentials his “oblogintrycount” attribute will keep on incrementing. Once this value exceeds the value configured in oam-config.xml the user will be redirected to “AccountLockedURL”.

Now to change the flag to false or update the login try count, OIM comes into picture. Using OIM APIs for change password or unlock account, these attribute values could be set to false(obpasswordchangeflag) or 0(oblogintrycount) respectively.

OAM checks for these values when two conditions are satisfied, first IdentityServiceEnabled is true and secondly user identity store (used for authenticating the user) in OAM is a default store.  Only then these attributes are validated. Else OAM ignores and authenticates the user and redirects the user to the landing page. 
In an OAM-OIM integrated environment for OAM to honour password management attributes its very important that user directory store used for authentication is set as default store.

Also another important thing to know is that while setting up resources, policies and authentication schemes, the authentication level of force change password page (configured in oam-config.xml) should be lower than the authentication level of protected application. If its set to same level, when a user is redirected to force change password page (when obpasswordchangeflag is true), and user opens another tab in the same browser to access the protected application,  user will be redirected to the protected resource even when his/her password's state in LDAP is temporary.