Getting started with the ForgeRock Identity Cloud REST API: Part 2 -

Author:

Rajesh Rajasekharan

Created at:

Jul 2023

Updated at:

Mar 2024

This is Part 2 of 8 in the series Getting started with the ForgeRock Identity Cloud REST API.

Prerequisite requests

This guide provides examples of running the ForgeRock Identity Cloud Collection prerequisite requests using both Postman and curl commands.

Before you begin

This guide assumes that you already have already prepared the ForgeRock Identity Cloud Postman Collection environment. See Part 1 - Introduction for further information.

Example using Postman ~ 5 min

  1. In Postman, select the ForgeRock Identity Cloud Postman Collection, and expand the Prerequisites section.

    https://backstage-community-prod.storage.googleapis.com/original/2X/d/d5c175f93918ba1d763fbb5bc0f33e3e137a6f1a

    At a high level, the REST API calls from Step 1 through to Step 2b do the following: * Step 1: Sends a request to the Identity Cloud authenticate REST endpoint for the authentication requirements. * Step 2(a): Using the authentication requirements received in Step 1, another request is sent to the authenticate REST endpoint by adding user credentials in the body of the request. * Step 2(b): Sends one more request to the authenticate REST endpoint, responding to the choice to set up a device for Multi Factor Authentication or skip it. On completing this step, a user session is created in Identity Cloud and a session token is returned.

  2. Under Prerequisites, click Step 1 to study the following:

    • The request type: POST

    • The request URL: {{amUrl}}/json/authenticate

    • The Headers section

      https://backstage-community-prod.storage.googleapis.com/original/2X/8/827155b81f5bd98fa6886a4d272d96f407b8281f

  3. With Prerequisites > Step 1 selected, click Send.

    https://backstage-community-prod.storage.googleapis.com/original/2X/7/71c1c56f12e1578740ccea4c045351ae2e22c598

    The JSON response from the Identity Cloud authenticate REST endpoint gives the authentication requirement. In this instance, the requirements are a username and a password.

    https://backstage-community-prod.storage.googleapis.com/original/2X/8/82e68d274942987c15731b9fb470e086c8272ea3

  4. Under Prerequisites, click Step 2a to study the following:

    • The request type: POST

    • The request URL: {{amUrl}}/json/authenticate

    • The Body Section where the postmanAdminUser credentials, set as variable values, are sent

      https://backstage-community-prod.storage.googleapis.com/original/2X/2/2e845f96aaee1e2ece3430a2cc4b9974d6cae511

  5. With Prerequisites > Step 2a selected, click Send.

    The JSON response is returned from the authenticate REST endpoint, and prompts the user to either set up a device for Multi Factor Authentication or skip it.

    https://backstage-community-prod.storage.googleapis.com/original/2X/b/bc93369bf1a9daf484116948f5c595da4c79e392

  6. Under Prerequisites, click Step 2b to study the following:

    • The request type: POST

    • The request URL: {{amUrl}}/json/authenticate

    • The Body Section where the user decides to skip the Multi Factor Authentication option.

      https://backstage-community-prod.storage.googleapis.com/original/2X/2/20f2d07c9b268eef18669aeaa4c911ce2dfe12dc

  7. With Prerequisites > Step 2b selected, click Send.

    The Identity Cloud authentication requirements are now completed. The Identity Cloud “authenticate” REST endpoint now returns a session token for the authenticated user.

    https://backstage-community-prod.storage.googleapis.com/original/2X/5/5f13a27a38be93c5e555671b5472b90cc1c8a27c

    Using the session token created for the postmanAdminUser, additional administrative activities can be performed on the Identity Cloud tenant. Recall that the postmanAdminUser has the openidm-admin authorization role assigned.

    Step 3 through to Step 5 of the Prerequisites section are used to create the following OAuth clients: * Step 3 creates postmanAdminClient * Step 4 creates postmanConfidentialClient * Step 5 creates postmanPublicClient

  8. Under Prerequisites, click Step 3 and study the following:

    • The request type: PUT

    • The request URL: {{amUrl}}/json{{realm}}/realm-config/agents/OAuth2Client/{{postmanConfidentialClientId}}

    • The Headers section, hover the mouse over the adminSSOToken variable and notice that it has the value set to the token returned in the earlier call.

      https://backstage-community-prod.storage.googleapis.com/original/2X/5/5d29a464d2296eaf3f3edf95846d77a35868e6f7

  9. Before sending the REST request to create OAuth profiles in Identity Cloud, log into the Identity Cloud tenant Admin UI. In the alpha realm, go to Applications to take note of any existing client profiles. A new application will be created later when we send the request to create a new OAuth client.

    https://backstage-community-prod.storage.googleapis.com/original/2X/4/483b9e5ec38396bc1a9d6eac25d0cc7101c0280d

  10. With Prerequisites > Step 3 selected, click Send.

  11. Examine the JSON response indicating the successful creation of OAuth Client in Identity Cloud.

https://backstage-community-prod.storage.googleapis.com/original/2X/0/06bae2b5a959adb6b21a4af9e025d6bfe79b84dd

  1. To confirm the creation of an OAuth client profile in Identity Cloud, log into the Identity Cloud Admin UI and go to Applications. The new OAuth client is listed.

    https://backstage-community-prod.storage.googleapis.com/original/2X/d/d9a5a9bc649b15ee7f8e18bb62a69a98be5ee577

  2. In Postman, under Prerequisites, examine Step 4 and Step 5. Send the REST requests in each step to create two more OAuth clients, which will be used for various OAuth 2.0 grant types in the OAuth 2.0 Flows section of the Identity Cloud Postman Collection.

  3. To confirm the creation of two more OAuth client profiles in Identity Cloud, log into the Identity Cloud Admin UI. In the alpha realm, go to Applications.

    All three OAuth client profiles created using the REST calls are listed.

    https://backstage-community-prod.storage.googleapis.com/original/2X/c/c9fece927fcf125c183cb3a483ef59a32a40c3b9

    Step 6 of the Prerequisites section is summarized as follows:

    Using the “postmanAdminClient” OAuth 2.0 application configured earlier, a POST request is sent to the Identity Cloud “access_token” REST endpoint for acquiring an access token with scope fr:idm:*. The request uses Resource Owner Password Credential (ROPC) grant type of OAuth 2.0, so the credentials of postmanAdminuser is also included in the request.

  4. Under Prerequisites, click Step 6 and study the following:

    • The request type: POST

    • The request URL: {{amUrl}}/oauth2{{realm}}/access_token

    • The Body section

https://backstage-community-prod.storage.googleapis.com/original/2X/1/18fd59d664ecfa8a04a76d4a427f461c3cf7dd19

  1. With Prerequisites > Step 6 selected, click Send.

    The “access_token” endpoint of Identity Cloud, returns an access token with scope fr:idm:* to the “postmanAdminClient” OAuth application.

    https://backstage-community-prod.storage.googleapis.com/original/2X/8/80379ba355b6f4563a90770e766f34957662e77e

    Step 7 of the Prerequisites section uses the access token obtained from Step 6 to perform the administrative task of creating a user in the alpha realm of the Identity Cloud Admin UI.

  2. Under Prerequisites, click Step 7 and study the following:

    • The request type: POST

    • The request URL:` {{platformUrl}}/openidm/managed/alpha_user?_action=create`

    • The Body section (some attribute values of users are picked up from the variables configured earlier, some are randomly generated).

https://backstage-community-prod.storage.googleapis.com/original/2X/2/2c8282c990afde23f84daf283695d5253e3e39e9

  1. With Prerequisites > Step 7 selected, click Send.

  2. Examine the JSON response indicating the successful creation of a user account.

https://backstage-community-prod.storage.googleapis.com/original/2X/2/2c8282c990afde23f84daf283695d5253e3e39e9

  1. To confirm that the new user was created, log into the Identity Cloud Admin UI, and go to Identities > Manage.

    The new Identity Cloud user who was created using the REST API is listed.

    https://backstage-community-prod.storage.googleapis.com/original/2X/7/7cd0f0d7db8788e93d102cb14833737824575a54

Examples using curl ~ 5 min

Besides Postman, the Identity Cloud REST APIs can also be invoked using curl.

This section of the guide revisits a couple of steps from the Prerequisites section of the ForgeRock Identity Postman Collection using the widely used curl command.

Use the OS command line terminal to run two examples of curl command below to:

  • Request an access token with scope fr:idm:* from the Identity Cloud “access token” endpoint using the OAuth ROPC grant type (Step 6 of ForgeRock Identity Cloud Postman Collection).

  • Use the access token obtained above to create a new ForgeRock Identity Cloud user (Step 7 of ForgeRock Identity Cloud Postman Collection).

To run the curl commands:

  1. Make a request for an access token. The backward slash indicates that the command continues in the next line. Don’t forget to replace the https link with your Identity Cloud tenant URL.

    $ curl \
 --header 'Content-Type: application/x-www-form-urlencoded ' \
 --data 'grant_type=password' \
 --data 'username=postmanAdminUser' \
 --data 'password=Rock5tar10$' \
 --data 'scope=fr:idm:*' \
 --data 'client_id=postmanAdminClient' \
 --data 'client_secret=postmanClientSecret' \
'https://<id_cloud_tenant>/am/oauth2/realms/root/realms/alpha/access_token'

    Example response:

        {
       "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyZTM2Y2JkYS02NmI2LTRiYWYtODY1ZS1jNDQxN2U5NmE1MjMiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXV0aF9sZXZlbCI6MCwiYXVkaXRUcmFja2luZ0lkIjoiMDA4YzE2MjYtN2QxNi00OTBiLWEwNjUtNGFhNmU2YWVhYzkzLTE4NTAwNDMiLCJzdWJuYW1lIjoiMmUzNmNiZGEtNjZiNi00YmFmLTg2NWUtYzQ0MTdlOTZhNTIzIiwiaXNzIjoiaHR0cHM6Ly9vcGVuYW0tdW5pLXJhamVzaC5mb3JnZWJsb2Nrcy5jb206NDQzL2FtL29hdXRoMi9yZWFsbXMvcm9vdC9yZWFsbXMvYWxwaGEiLCJ0b2tlbk5hbWUiOiJhY2Nlc3NfdG9rZW4iLCJ0b2tlbl90eXBlIjoiQmVhcmVyIiwiYXV0aEdyYW50SWQiOiJzZlFZUnhBOGk1MkU2ZUlYWVF5WVJoci13NzAiLCJhdWQiOiJwb3N0bWFuQWRtaW5DbGllbnQiLCJuYmYiOjE2ODI3NzY5MzQsImdyYW50X3R5cGUiOiJwYXNzd29yZCIsInNjb3BlIjpbImZyOmlkbToqIl0sImF1dGhfdGltZSI6MTY4Mjc3NjkzNCwicmVhbG0iOiIvYWxwaGEiLCJleHAiOjE2ODI3ODA1MzQsImlhdCI6MTY4Mjc3NjkzNCwiZXhwaXJlc19pbiI6MzYwMCwianRpIjoiM29GQTgtRkg4eVZueVBialFBYi1UNXBOek9nIn0.TYAsmF93vVmCzTcC751SLQwNo-J9fBi30u2O-ImwSdI",
       "scope": "fr:idm:*",
       "token_type": "Bearer",
       "expires_in": 3599
     }

  2. The following command creates an Identity Cloud user using the access token received above.

     $ curl  \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer <access_token obtained above>' \
 --data '{
   "userName": "postmanDemoUser2",
   "sn": "Demo-User2",
   "givenName": "Postman",
   "mail": "demo.user2@postman.example.com",
   "telephoneNumber": "777-777-7777",
   "password": "Rock5tar10$"
 }' 'https://<id_cloud_tenant>/openidm/managed/alpha_user?_action=create'

    Example response:

        {
       "_id": "d2f094a2-ad6f-4166-bb04-141af54ac61e",
       "_rev": "84bdb827-942c-40c2-ab91-91645583d69f-17075",
       "country": null,
       "frUnindexedString1": null,
       "mail": "demo.user2@postman.example.com",
       "memberOfOrgIDs": [],
       &lt; ------------output omitted for brevity ---------->
       "telephoneNumber": "777-777-7777",
       "city": null,
       &lt; ------------output omitted for brevity ---------->
       "sn": "Demo-User2",
       "frUnindexedDate1": null,
       "frIndexedInteger5": null,
       "preferences": null,
       "userName": "postmanDemoUser2",
       "frIndexedDate2": null,
       "frIndexedDate1": null,
       "effectiveRoles": []
     }

  3. To confirm that the new user was created in the Identity Cloud alpha realm, log into your Identity Cloud Admin UI, and go to Identities > Manage. The new Identity Cloud user created using the curl command is listed.

    https://backstage-community-prod.storage.googleapis.com/original/2X/9/91090bfdda564e1bb8e8ccb15c35bfb2d2cbe1c4

Further reading

Other guides in the Getting started with the ForgeRock Identity Cloud REST API series:

Other useful links: