Postman Collection

The ForgeRock Identity Cloud provides a number of REST API endpoints to help you manage identities, authenticate to the system, monitor Identity Cloud, and more.

To help you quickly use and understand these endpoints, ForgeRock provides a Postman collection, containing examples of a number of features you can manage using the REST API.

Features included:
 
・Intelligent Access
・User Self-Service
・Session Management
・Identity Profiles
・Managed Identities
・Auditing/Monitoring
・OAuth 2.0 Flows

postman collection overview

Getting started

  1. Download and install Postman.

  2. Download the ForgeRock Identity Cloud Postman Collection.

  3. In Postman:

    1. Go to File > Import…​ > Upload Files.

    2. Browse to the ForgeRock Postman Collection JSON file you downloaded earlier, and then click Open.

    3. Click Import to bring the collection into your workspace.

Preparing your Identity Cloud

To use the collection, you must create an identity in Identity Cloud that the collection can connect with.

  1. Log in to the ForgeRock Identity Cloud as an administrator.

  2. Ensure you are managing the Alpha realm.

    1. If not, select the current realm in the top-left corner, click Switch realm…​, and switch to the alpha realm.

  3. Go to Identities > Manage > Users, and then click + New User.

  4. Specify a Username, for example postmanAdminUser.

  5. Complete the remaining fields, and then click Save.

  6. On the Manage Identities page, click the username you just created.

  7. Click Reset Password, then provide a suitable value.

  8. Select Authorization Roles, and then click Add Authorization Roles.

  9. Add the openidm-admin and openidm-authorized roles, and then click Save.

The Postman Collection can now authenticate to Identity Cloud using these credentials.

Proceed to Configuring the collection to enter these credentials, plus other settings necessary to use the collection.

Configuring the collection

The ForgeRock Identity Cloud Postman Collection uses a number of variables, with placeholder values, to form the REST requests.

For example, the collection needs to know the Identity Cloud URL, as well as credentials for connecting.

Before using the collection, you must provide the following properties:

Table 1. Required Collection Variables
Variable Default Description

platformUrl

https://myTenant.forgeblocks.com

Specifies the root URL of your Identity Cloud.

amUrl

https://myTenant.forgeblocks.com/am

Specifies the URL of the Access Management (AM) component of your Identity Cloud.

idmUrl

https://myTenant.forgeblocks.com/openidm

Specifies the URL of the Identity Management (IDM) component of your Identity Cloud.

realm

/realms/root/realms/alpha

Specifies the realm that the majority of the requests in the collection target.

You must specify the entire hierarchy of the realm, starting at the Top Level Realm.

Prefix each realm in the hierarchy with the realms keyword.
Example: /realms/root/realms/customers/realms/europe.

IDCloudAdminUsername

admin@example.com

Specifies the username of an administrative user that can authenticate to the top-level realm, and create OAuth 2.0 clients and managed users.

IDCloudAdminPassword

Password1!

Specifies the password of the administrative user above.

logApiKey

Not Set

Specifies the API key used to access the monitoring endpoints.

logApiSecret

Not Set

Specifies the API secret used to access the monitoring endpoints.

You can also override the default collection-level variables by creating a Postman Environment. Use the same variable names as those in the table above.

For information on creating a Postman Environment, see Managing environments in the "Postman Learning Center".

To configure Postman collection variables

  1. In Postman, on the Collections tab, select ForgeRock Identity Cloud Collection, select View more actions (), and then click Edit.

  2. On the Variables tab, find the variable to edit, and enter the value in the INITIAL VALUE column.

  3. Repeat the previous step to enter all the required variable values, and then click Update.

You can now start using the collection, or customize the collection further by configuring optional variables.

Configuring optional variables

The ForgeRock Identity Cloud Postman Collection uses a number of additional variables to define the requests it makes, and some of the setup it performs. For example, the credentials of demonstration users and OAuth 2.0 client identifiers.

Before using the collection, you may decide to alter the default values of these variables to suit your environment.

If you choose to alter the default, use the steps described in To configure Postman Collection variables.

Using the collection

To use the ForgeRock Identity Cloud Postman Collection, you should run through the Prerequisite requests, which configures your Identity Cloud with the necessary elements, such as OAuth 2.0 clients and demonstration users.

Running the prerequisite steps

Ensure you have configured the required collection variables as described in Configuring the collection before running the prerequisite steps.
  1. In Postman, with the ForgeRock Identity Cloud collection loaded, open the Prerequisites section.

  2. Select the first request in the list, examine the details, and when happy to do so, click the Send button.

    Many of the requests have associated tests; for example, that the response code was 200. Postman displays the test results alongside the response to the request.

    Many of the requests will set a global variable containing a value returned in the response, for use in subsequent requests.

    The details of these can be seen in the Tests tab of a request. You can also view the values of these global variables by clicking Environment Quick Look ().

  3. Repeat the previous step for each request in the Prerequisites folder.

When completed, Identity Cloud will contain the following:

  • Three OAuth 2.0 clients:

    1. A client named postmanAdminClient, which provides an access token that can be used to administer the /alpha realm.

    2. A client named postmanConfidentialClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

    3. A client named postmanPublicClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

  • Two "alpha_user" identities:

    1. A postmanAdminUser identity, which connects to the postmanAdminClient in order to perform realm administration requests.

    2. A postmanDemoUser identity, which demonstrates a number of user-related endpoints, such as identity profiles, and user self-service.

If you need to recreate any of the above, or decide to alter the default values, run each of the steps in the Prerequisite folder again.

Running the requests

The requests in the collection are split into different features. To run the calls for a feature, open the relevant folder, and run each request in sequence.

Note that the following topics have additional functionality, see each section for details.

Intelligent access

There are scripts in the Intelligent Access requests that attempt to detect the callbacks that the first step returns, and sets the next request to handle it.

To view the details of this script:

  1. In Postman, on the Collections tab, select ForgeRock Identity Cloud Collection, select View more actions (), and then click Edit.

  2. On the Pre-request Scripts tab, examine the detectCallbacks script.

When manually running through the steps, examine the response returned in the first call, and run relevant next step. The collection is able to handle the following ready-to-use callbacks:

Table 2. Intelligent Access Callback Steps
Step Callback

Step 2a

Username and password callbacks, together in a page node.

Step 2b

Validated create username and password callbacks, together in a page node.

Step 2c

Choice callbacks.

Step 2d

Text input callbacks.

Step 2e

Device profile callbacks. See Configure Device Profiling.

Step 2f

Progressive profile callbacks.

Identity profiles

Some endpoints require the ID of an identity, rather than the username.

An example of this is when getting the OAuth 2.0 profiles a user has provided consent to.

When running the Identity Profiles requests, ensure you have also executed the request named Step 3. Get Users' ID.

The result is stored in the demoUserId global variable.

More information