REST APIs

Identity Cloud provides REST APIs to help you manage identities, authenticate to the system, monitor Identity Cloud, and more. These are documented in the Identity Cloud Postman Collection.

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

Identity Cloud Postman Collection

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

  1. Download and install Postman.

  2. Download the Identity Cloud Postman collection.

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

  1. Log in to the 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. Enter the Username as "postmanAdminUser".

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

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

  7. Click Reset Password, then enter a new password.

    Make sure that you use a strong password.

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

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

postman collection variables

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

platformUrl

https://<tenant-name>.forgeblocks.com

Specifies the root URL of your Identity Cloud.

amUrl

https://<tenant-name>.forgeblocks.com/am

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

idmUrl

https://<tenant-name>.forgeblocks.com/openidm

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

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

Not Set

Specifies the password of the administrative user 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

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

cookieName

iPlanetDirectoryPro

Specifies the name of the session cookie for AM sessions.
+ You are recommended to change the default variable value as a security best practice.

loginJourney

Login

Specifies the authorisation journey name to use.
+ See Login.

redirect_uri

https://httpbin.org/anything

Specifies the URI 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

To use the 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 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.
  1. In Postman, with the 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. Click on the top level of the collection menu (labelled "ForgeRock Identity Cloud Collection"), then select the Pre-request Scripts tab.

  2. Within the 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 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.

Accessing the AM REST APIs

You can use many, but not all, of the Access Management APIs with Identity Cloud. Before you can authenticate to the AM API server, you must first obtain a key and access token.

Obtaining AM API credentials

  1. In the Admin UI, click the user icon, and then click Tenant Settings.

    Show me

    tenant menu

  2. On the Global Settings tab, click Log API Keys.

  3. Click New Log API Key, provide a name for the key, and then click Create Key.

    A dialog box appears containing the new keys:

    log api key
  4. Store the api_key_id and api_key_secret values securely.

    You cannot view the api_key_secret value again once you click Done.
  5. Click Done.

    For a comprehensive list of AM APIs, see the AM REST API Explorer.

Accessing the IDM REST APIs

You can use many, but not all, of the Identity Management APIs with Identity Cloud.

Before you can authenticate to the IDM API server, must first obtain an access token. The access token must include:

  • IDM admin privileges

  • The fr:idm:* scope

Getting a user access token

There are many different ways to get a user access token. One way is to use the Identity Cloud Postman Collection.

  1. Follow the instructions for Getting Started with the Postman Collection:

  2. In the Postman Collection, click Prerequisites.

  3. To create an admin user and set the scope, complete Steps 1 through 3.

    Show me where

    postman admin user

  4. To generate a token, complete any one of flows in the OAuth 2.0 directory.

    Show me where

    postman oauth2 flows

Authenticate to the IDM API server

  1. Set a shell environment variable with your access token value.

    Example:
    export TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkNWE4NDVjMy03MjFh
    LTQzN2QtYjIyZi04ZjNlNzUyNDExNWIiLCJjdHMiOiJPQVVUSDJfR1JBTlRfU0VUIiwiYXV0aF9sZXZ
    lbCI6MCwiYXVkaXRUcmFja2luZ0lkIjoiYjU4M2Q2NGUtM2VlYi00M2Y5LWI5ZTctZDM4MDI4MDQyYW
    JmLTY0MyIsImlzcyI6Imh0dHBzOi8vb3BlbmFtLWNhcmlhZ2EtMDUuZm9yZ2VibG9ja3MuY29tL2FtL"
  2. Run a command like this example, replacing <tenant> with your tenant name:

    curl \
      -H 'authorization: Bearer '"$TOKEN" \
      --header "Accept-API-Version: resource=1.0" \
      --request POST \
      'https://<tenant-name>.forgeblocks.com/openidm/system?_action=availableConnectors'

    For a comprehensive list of IDM APIs, see the IDM REST API Explorer.

More information