Interact with IDM
There are two primary ways to interact with IDM; programmatically, using REST to access IDM’s API endpoints, or using the browser-based user interfaces.
REST interface introduction
IDM provides RESTful access to users in its repository, and to its configuration. To access the repository over REST, you can use a browser-based REST client, such as the Simple REST Client for Chrome, or RESTClient for Firefox. You can also use applications such as Postman to create, run, and manage collections of REST calls. Alternatively you can use the curl command-line utility, included with most operating systems. For more information about curl, see https://github.com/curl/curl.
IDM is accessible over the regular and secure HTTP ports of the Jetty Servlet container, 8080, and 8443. Most of the command-line examples in this documentation set use the regular HTTP port, so that you don’t have to use certificates just to test IDM. In a production deployment, install a CA-signed certificate and restrict REST access to a secure (HTTPS) port.
To run curl over the secure port, 8443, you must either include the --insecure option, or follow the instructions in Restrict REST Access to the HTTPS Port. You can use those instructions with the self-signed certificate that is generated when IDM starts, or with a *.crt file provided by a certificate authority.
|
Some of the examples in this documentation set use client-assigned IDs (such as |
Try Out IDM Using REST
-
Use the following REST query to list all users in the IDM repository:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/?_queryFilter=true&_fields=_id"
When you first install IDM with an empty repository, no users exist.
-
Create a user
joeby sending a RESTful POST.The following
curlcommand creates a managed user in the repository, and set the user’s ID tojdoe:curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "password": "TestPassw0rd", "description": "My first user", "_id": "joe" }' \ http://localhost:8080/openidm/managed/user?_action=create { "_id": "joe", "_rev": "00000000c03fd7aa", "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "description": "My first user", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] }curl ` --header "Content-Type: application/json" ` --header "X-OpenIDM-Username: openidm-admin" ` --header "X-OpenIDM-Password: openidm-admin" ` --header "Accept-API-Version: resource=1.0" ` --request POST ` --data '{ "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "password": "TestPassw0rd", "description": "My first user", "_id": "joe" }' ` http://localhost:8080/openidm/managed/user?_action=create { "_id": "joe", "_rev": "00000000c03fd7aa", "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "description": "My first user", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } -
Fetch the newly created user from the repository with a RESTful GET:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ http://localhost:8080/openidm/managed/user/joe { "_id": "joe", "_rev": "00000000c03fd7aa", "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "description": "My first user", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] }curl ` --header "X-OpenIDM-Username: openidm-admin" ` --header "X-OpenIDM-Password: openidm-admin" ` --header "Accept-API-Version: resource=1.0" ` --request GET ` http://localhost:8080/openidm/managed/user/joe { "_id": "joe", "_rev": "00000000c03fd7aa", "userName": "joe", "givenName": "joe", "sn": "smith", "mail": "joe@example.com", "telephoneNumber": "555-123-1234", "description": "My first user", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] }
Format REST output for readability
By default, curl-based REST calls return the JSON object on one line, which can be difficult to read. For example:
{"mail":"joe@example.com","sn":"smith","passwordAttempts":"0",
"lastPasswordAttempt":"Mon Apr 14 2014 11:13:37 GMT-0800 (GMT-08:00)",
"givenName":"joe","effectiveRoles":["internal/role/openidm-authorized"],
"password":{"$crypto":{"type":"x-simple-encryption","value":{"data":
"OBFVL9cG8uaLoo1N+SMJ3g==","cipher":"AES/CBC/PKCS5Padding","iv":
"7rlV4EwkwdRHkt19F8g22A==","key":"openidm-sym-default"}}},"country":"",
"city":"","_rev": "00000000c03fd7aa","lastPasswordSet":"","postalCode":"",
"_id":"joe3","description":"My first user","accountStatus":"active","telephoneNumber":
"555-123-1234","roles":["internal/role/openidm-authorized"],"effectiveAssignments":{},
"postalAddress":"","stateProvince":"","userName":"joe3"}
At least two options are available to clean up this output:
Format Output Using a JSON Parser
The standard way to format JSON output is with a JSON parser such as jq. jq is not installed by default on most operating systems, but you can install it and then "pipe" the output of a REST call to jq, as follows:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/joe" \ | jq .
Format Output Using the REST API
The ForgeRock REST API includes an optional _prettyPrint request parameter. The default value is false. To use the ForgeRock REST API to format output, add a parameter such as ?_prettyPrint=true or &_prettyPrint=true, depending on whether it is added to the end of an existing request parameter. In this case, the following command would return formatted output:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/joe?_prettyPrint=true"
|
Most command-line examples in this guide do not show this parameter, but the output is formatted for readability. |
IDM user interfaces
IDM provides UIs at two different endpoints; / and /admin. The administrative tools available at /admin are called the admin UI. The End User UI enables end users to manage certain aspects of their own accounts.
For information about the admin UI, see IDM user interface .
For information about the End User UI, see Self-service end user UI.