Identity Cloud Postman collection

Identity Cloud provides REST APIs to help you manage identities, authenticate to the system, monitor Identity Cloud, and more.

You can also use the AM and IDM APIs with Identity Cloud.

To help you quickly use and understand these REST APIs, Identity Cloud provides a Postman collection, containing example requests grouped into features.

Features included:

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

postman collection overview

Getting started

Download and install Postman.
Download the Identity Cloud Postman collection.
In Postman:
1. Go to File > Import… > Upload Files.
2. Browse to the collection JSON file you downloaded in the previous step, and then click Open.
3. Click Import to bring the collection into your workspace.

Preparing your Identity Cloud

To use the Identity Cloud Postman collection, you must create a user identity in Identity Cloud that the collection requests can connect to.

Log in to the Identity Cloud as a tenant administrator.
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.
Go to Identities > Manage > Users, and then click + New User.
Enter the user name as "postmanAdminUser".
Complete the remaining fields, and then click Save.
On the Manage Identities page, click the user you just created.
Click Reset Password, then enter a new password.

Make sure that you use a strong password.
Select Authorization Roles, and then click Add Authorization Roles.
Add the openidm-admin and openidm-authorized roles, and then click Save.

The collection requests for managed users will authenticate to Identity Cloud using these credentials.

Proceed to the next section to learn how to enter these credentials, plus other settings necessary to use the collection.

Configuring the collection

The Identity Cloud Postman collection uses a number of variables to populate the requests. These variables are stored at collection level. To view them, click on the top level of the collection menu (labelled "ForgeRock Identity Cloud Collection"), then select the Variables tab.

The variables are initially set with placeholder values that you will need to modify or replace. For example, the collection needs to know the Identity Cloud URL, as well as your admin access credentials.

To edit the variables, enter new values in the INITIAL VALUE column. Then click Save to make the edits permanent.

See Required variable values to understand which variables you need to edit before you can use the collection. See Optional variable values to understand which variables you may want to edit to customize the collection to suit your environment.

You can then start using the collection.

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

Required variable values

Before using the collection, you must provide the following variable values:

Make sure that you use strong passwords for access credentials.

Variable Default Description

Variable	Default	Description
`platformUrl`	https://<tenant-env-fqdn>	Specifies the root URL of your Identity Cloud.
`amUrl`	https://<tenant-env-fqdn>/am	Specifies the URL of the Access Management (AM) component of your Identity Cloud.
`idmUrl`	https://<tenant-env-fqdn>/openidm	Specifies the URL of the Identity Management (IDM) component of your Identity Cloud.
`IDCloudAdminUsername`	admin@example.com	Specifies the username of an Identity Cloud adminstrator who can authenticate to the top-level realm, and create OAuth 2.0 clients and managed users.
`IDCloudAdminPassword`	Not Set	Specifies the password of the Identity Cloud adminstrator above.
`postmanClientSecret`	Not Set	Specifies the password to be used by the OAuth 2.0 administrative, private, and public clients. These clients are created when you run the Prerequisite requests from the collection.
`postmanAdminPassword`	Not Set	Specifies the password to be used by the OAuth 2.0 managed admin user. This is the password you set up in Preparing your Identity Cloud.
`postmanDemoPassword`	Not Set	Specifies the password to be used by OAuth 2.0 managed realm user. The realm user is created when you run the Prerequisite requests from the collection.
`logApiKey`	Not Set	Specifies the API key used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only. See Obtaining API Credentials.
`logApiSecret`	Not Set	Specifies the API secret used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only. See Obtaining API Credentials.

platformUrl

https://<tenant-env-fqdn>

Specifies the root URL of your Identity Cloud.

amUrl

https://<tenant-env-fqdn>/am

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

idmUrl

https://<tenant-env-fqdn>/openidm

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

IDCloudAdminUsername

admin@example.com

Specifies the username of an Identity Cloud adminstrator who can authenticate to the top-level realm, and create OAuth 2.0 clients and managed users.

IDCloudAdminPassword

Not Set

Specifies the password of the Identity Cloud adminstrator above.

postmanClientSecret

Not Set

Specifies the password to be used by the OAuth 2.0 administrative, private, and public clients.

These clients are created when you run the Prerequisite requests from the collection.

postmanAdminPassword

Not Set

Specifies the password to be used by the OAuth 2.0 managed admin user.

This is the password you set up in Preparing your Identity Cloud.

postmanDemoPassword

Not Set

Specifies the password to be used by OAuth 2.0 managed realm user.

The realm user is created when you run the Prerequisite requests from the collection.

logApiKey

Not Set

Specifies the API key used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only.

See Obtaining API Credentials.

logApiSecret

Not Set

Specifies the API secret used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only.

See Obtaining API Credentials.

Optional variable values

The collection uses the following additional variables, which will work using their default values, although you may want to modify them later:

Variable Default Description

Variable	Default	Description
`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".
`customDomainUrl`	https://id.mycompany.com	Specifies a custom domain that can be used for domain specific requests such as "/.well-known/assetlinks.json".
`cookieName`	iPlanetDirectoryPro	Specifies the name of the session cookie for AM sessions. Change the default variable value as a security best practice.
`loginJourney`	Login	Specifies the authorization journey name to use. See Login.
`redirect_uri`	https://httpbin.org/anything	Specifies the URI to which the OAuth 2.0 client will redirect the user upon a successful authentication request.
`postmanAdminClientId`	postmanAdminClient	Specifies the username to be used for the OAuth 2.0 administrative client.
`postmanConfidentialClientId`	postmanConfidentialClient	Specifies the username to be used for the OAuth 2.0 private client.
`postmanPublicClientId`	postmanPublicClient	Specifies the username to be used for the OAuth 2.0 public client.
`postmanAdminUsername`	postmanAdminUser	Specifies the username to be used for the OAuth 2.0 managed admin user This is the username you set up in Preparing your Identity Cloud.
`postmanDemoUsername`	postmanDemoUser	Specifies the username to be used for the OAuth 2.0 managed realm user.
`postmanDemoEmail`	demo.user@postman.example.com	Specifies the email to be used for the OAuth 2.0 managed realm user.

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

customDomainUrl

https://id.mycompany.com

Specifies a custom domain that can be used for domain specific requests such as "/.well-known/assetlinks.json".

cookieName

iPlanetDirectoryPro

Specifies the name of the session cookie for AM sessions.

Change the default variable value as a security best practice.

loginJourney

Specifies the authorization journey name to use.

See Login.

redirect_uri

https://httpbin.org/anything

Specifies the URI to which the OAuth 2.0 client will redirect the user upon a successful authentication request.

postmanAdminClientId

postmanAdminClient

Specifies the username to be used for the OAuth 2.0 administrative client.

postmanConfidentialClientId

postmanConfidentialClient

Specifies the username to be used for the OAuth 2.0 private client.

postmanPublicClientId

postmanPublicClient

Specifies the username to be used for the OAuth 2.0 public client.

postmanAdminUsername

postmanAdminUser

Specifies the username to be used for the OAuth 2.0 managed admin user

This is the username you set up in Preparing your Identity Cloud.

postmanDemoUsername

postmanDemoUser

Specifies the username to be used for the OAuth 2.0 managed realm user.

postmanDemoEmail

demo.user@postman.example.com

Specifies the email to be used for the OAuth 2.0 managed realm user.

Using the collection

Before using the Identity Cloud Postman collection, you should run the Prerequisite requests. The requests configure your Identity Cloud with the necessary elements, such as OAuth 2.0 clients and managed users

Running the prerequisite requests

Ensure you have configured the required collection variables as described in Configuring the collection before running the prerequisite requests.

In Postman, with the Identity Cloud collection loaded, open the Prerequisites section.
Select the first request in the list, examine the details, and when you’re satisfied the request is properly formed, click Send.

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 ().
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 intelligent access and identity profiles 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:

Click on the top level of the collection menu (labelled ForgeRock Identity Cloud Collection), then select the Pre-request Scripts tab.
Within the tab, examine the detectCallbacks script.

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

Table 1. 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.