FAQ

FAQ: REST API in IDM/OpenIDM

Last updated Nov 2, 2020

The purpose of this FAQ is to provide answers to commonly asked questions regarding the REST API in IDM/OpenIDM.


Frequently asked questions

Q. Can I do a negation query with the REST API?

A. Yes, you can using the boolean operator ! (NOT). Examples of queries that can be performed via REST (with the equivalent LDAP filter for comparison) are shown in HTTP User Guide › Query.

Q. How do I find users who don't have any roles associated with them?

A. The effectiveRoles property is an array, which means you need to use a queryfilter to determine if an array is empty. You can use a negation query such as the following to return all users who have an empty effectiveRoles property assigned to them:

  • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" "http://localhost:8080/openidm/managed/user?_queryFilter=!(/effectiveRoles/0 pr)"
  • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/managed/user?_queryFilter=!(/effectiveRoles/0 pr)"

If you want to find users who have at least one role assigned to them, you would use this queryfilter instead (without the NOT ! boolean operator):

http://localhost:8080/openidm/managed/user?_queryFilter=(/effectiveRoles/0 pr)

See Object Modeling Guide › Effective Roles and Effective Assignments for further information.

Q. How do I remove elements of a string array from a managed object by relationship map?

A. It is not possible to remove elements of a string array by relationship map. See How do I remove elements of a string array using the REST Patch operation in IDM/OpenIDM (All versions)? for further information on removing elements of a string array.

Q. Why does my search on a new attribute not return all the expected results?

A. When you add an attribute, you must make it searchable to ensure the expected results are returned. You can make it searchable as follows:

  1. Update the repo.jdbc.json file (located in the /path/to/idm/conf directory) to add /newAttribute as a searchable field: "properties" : { [..] "/newAttribute" : { "searchable" : true }, [..] }
  2. Restart the IDM/OpenIDM instance.
  3. Run reconciliation or update a managed user with a value in the newAttribute attribute to force the object to be re-written to the repository with the new searchable properties; this will cause the managedobjectproperties table to be updated.
Note

You can set searchableDefault to true in the repo.jdbc.json file instead of setting the searchable property for individual attributes; however, this has an impact on performance and it is recommended that you only set the searchable property for the attributes that need to be searchable.

Q. Why can't I search managed user objects for attributes stored in arrays?

A. Attributes stored in arrays are not searchable by default. You can make attributes stored in arrays searchable as detailed in How do I search managed user objects for attributes stored in arrays in IDM/OpenIDM (All versions)?

Q. How do I ensure virtual attributes are returned when I query users in managed.json?

A. You can query a user object by specifying the user ID; this will return all attributes (including virtual), for example:

  • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" http://localhost:8080/openidm/managed/user/44a86e3c-f509-48b6-91a7-0bfc4ea53b7d
  • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/managed/user/44a86e3c-f509-48b6-91a7-0bfc4ea53b7d

However, if you do a query using a queryFilter, virtual attributes are excluded from the result.

Q. How can I delete a user regardless of its revision, for example, there is a mismatch of revisions?

A. If there is a mismatch of revisions, you will see a response similar to:

{"error":412,"reason":"Precondition Required","message":"Delete rejected as current Object revision 8 is different than expected by caller 7, the object has changed since retrieval."}

To ensure the user is deleted, you can execute the REST call with the "If-Match: *" header, for example:

  • IDM 7 and later: $ curl -X DELETE -H "If-Match: *" -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" http://localhost:8080/openidm/managed/user/jdoe
  • Pre-IDM 7: $ curl -X DELETE -H "If-Match: *" -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" http://localhost:8080/openidm/managed/user/jdoe

Q. Can I force a user to change their password in DS/OpenDJ via the IDM/OpenIDM REST API?

A. Yes you can. You can set the pwdReset attribute (set-password-is-reset) to true in the system/OpenDJ/account object. For example, you could use a REST call such as:

  • IDM 7 and later: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{"pwdReset": "true"}' http://localhost:8080/​openidm/system/openDJ/account/316cb3e8-446e-4328-b4d7-2e55b863977b
  • Pre-IDM 7: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" -d '{"pwdReset": "true"}' http://localhost:8080/​openidm/system/openDJ/account/316cb3e8-446e-4328-b4d7-2e55b863977b

The user will be forced to change their password when they next log in.

Note

pwdReset is an operational attribute; you should ensure an appropriate ACI exists for the account used by IDM/OpenIDM to bind to DS/OpenDJ.

See Self-Service Reference › REST Requests in a Password Reset Process (IDM 6 and later) or How do I initiate the password reset functionality in IDM 5.x and OpenIDM 4.x via the REST API? for a way of doing this regardless of where your passwords are stored.

Q. Can I lock and unlock a user's account in DS/OpenDJ via the IDM/OpenIDM REST API?

A. Yes you can by setting the ds-pwp-account-disabled attribute to true (to lock the account) and false (to unlock the account) in the system/OpenDJ/account object.

You can use a REST call such as the following to lock a user's account:

  • IDM 7 and later: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" -d '{"ds-pwp-account-disabled": "true"}' http://localhost:8080/​/openidm/system/openDJ/account/uid=jdoe,ou=people,dc=example,dc=com
  • Pre-IDM 7: $ curl -X PUT -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" -d '{"ds-pwp-account-disabled": "true"}' http://localhost:8080/​/openidm/system/openDJ/account/uid=jdoe,ou=people,dc=example,dc=com

Optionally, you can PATCH this change to the IDM/OpenIDM managed user and rely on your sync to update the DS/OpenDJ target.

Note

ds-pwp-account-disabled is an operational attribute; you should ensure an appropriate ACI exists for the account used by IDM/OpenIDM to bind to DS/OpenDJ.

Q. How can I find the available managed objectTypes via REST?

A. You can query the openidm/config/managed endpoint which reads managed.json, for example:

  • IDM 7 and later: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Accept-API-Version: resource=1.0" -H "Content-Type: application/json" http://localhost:8080/openidm/config/managed
  • Pre-IDM 7: $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/config/managed

And look for all the name attributes within the objects structure to identify all the available objectTypes.

See Also

Using the REST API in IDM/OpenIDM

Setup Guide › Configure the Server Over REST

External Services Guide › Access External REST Services

REST API Reference

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)



Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.
Loading...