FAQ

FAQ: REST API in IDM/OpenIDM

Last updated Nov 7, 2018

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 Developer's Guide › Querying Resource Collections.

Q. How do I define the Content-Type header when using an external REST call?

A. IDM/OpenIDM sets the Content-Type header to application/json in external REST calls even if you specify a different header value. If you need this header to be anything other than application/json, you must use the contentType parameter in your external REST call.

For example, to specify your Content-Type as application/x-www-form-urlencoded in your external REST call:

$ curl -H "Content-Type: application/json" -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: password" -X POST -d '{ 
   "url": "https://host1.example.com:18080/openam/oauth2/access_token", 
   "method": "POST", 
   "detectResultFormat": false, 
   "body": "grant_type=client_credentials", 
   "authenticate" : {"type": "basic", "user" : "Test", "password" : "password"}, 
   "contentType" : "application/x-www-form-urlencoded"
}' "http://localhost:8080/openidm/external/rest?_action=call"

See 500-Internal server error when calling external REST endpoint from workflow in IDM/OpenIDM (All versions) for further information on this issue.

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 (All versions) and OpenIDM 4.x? 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:

$ 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:

$ 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:

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

If you are using OpenIDM 4.x or IDM, see How do I initiate the password reset functionality in IDM (All versions) and OpenIDM 4.x via the REST API? for a way of doing this within IDM/OpenIDM 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:

$ 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:

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

Q. How do I delete a schedule via REST?

A. You can delete a schedule as follows depending on your version:

IDM 5 and later

  1. Query the _id of the schedule you want to delete using the following REST call:
    $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/scheduler/job?_queryId=query-all-ids
    Example response:
    { 
      "result": [ 
        { 
          "_id": "910d2bc5-a04b-66f6-aa74-eb365e47b6d3" 
        } 
      ], 
      "resultCount": 1, 
      "pagedResultsCookie": null, 
      "totalPagedResultsPolicy": "NONE", 
      "totalPagedResults": -1, 
      "remainingPagedResults": -1 
    }
    
  2. Delete the schedule using the following REST call, where 910d2bc5-a04b-66f6-aa74-eb365e47b6d3 is the _id value returned in step 1:
    $ curl -X DELETE -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/scheduler/job/910d2bc5-a04b-66f6-aa74-eb365e47b6d3"

Pre-IDM 5

  1. Query the _id of the schedule you want to delete using the following REST call:
    $ curl -X GET -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" -H "Content-Type: application/json" http://localhost:8080/openidm/scheduler?_queryId=query-all-ids
    Example response:
    { 
      "result": [ 
        { 
          "_id": "910d2bc5-a04b-66f6-aa74-eb365e47b6d3" 
        } 
      ], 
      "resultCount": 1, 
      "pagedResultsCookie": null, 
      "totalPagedResultsPolicy": "NONE", 
      "totalPagedResults": -1, 
      "remainingPagedResults": -1 
    }
    
  2. Delete the schedule using the following REST call, where 910d2bc5-a04b-66f6-aa74-eb365e47b6d3 is the _id value returned in step 1:
    $ curl -X DELETE -H "X-OpenIDM-Username: openidm-admin" -H "X-OpenIDM-Password: openidm-admin" "http://localhost:8080/openidm/scheduler/910d2bc5-a04b-66f6-aa74-eb365e47b6d3"

See Also

Using the REST API in IDM/OpenIDM

Integrator's Guide › Configuring the Server Over REST

Integrator's Guide › Accessing External REST Services

Integrator's Guide › REST API Reference

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)



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