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

[rajeshr]

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

Introduction to REST APIs in Identity Cloud ~ 5 min

ForgeRock Identity Cloud is a ForgeRock managed Identity and Access Management solution hosted on Google Cloud Platform (GCP), with unmatched security architecture built for Enterprise.

REST stands for Representational State Transfer. As an architectural style for building web services, it uses the HTTP protocol to enable communication between systems. In a RESTful architecture, each resource is represented by a Uniform Resource Identifier (URI), and the resource can be operated on by sending various HTTP requests (GET, POST, PUT, DELETE etc.) to the URI.

Identity Cloud has published HTTP endpoints for various functionalities. REST clients can invoke HTTP calls to the Identity Cloud REST APIs to use its various functionalities.

As an example, for a quick health check of an Identity Cloud tenant, use a REST client to invoke HTTP request to its publicly accessible endpoint “/monitoring/health” as shown below.

Request:

$ curl --request GET 'https://<id-cloud-tenant>/monitoring/health'

Response:

{
  "status": "OK"
}

The “/monitoring/health” HTTP endpoint does not require authentication, but other Identity Cloud REST APIs requests require either an access token or Log API keys.

About this guide

This is Part 1 of 8 in a series of articles that make up the Getting Started guide for using the REST API with Identity Cloud. The other guides in the series are:

• Part 2 - Prerequisites
• Part 3 - Intelligent Access
• Part 4 - User self-service
• Part 5 - Session management
• Part 6 - Identity profiles & OAuth 2.0 flows
• Part 7 - Managed identities
• Part 8 - Auditing and monitoring

The guides walk through most of the use cases made available in the Identity Cloud Postman Collection. Wherever feasible, the command line equivalent of REST requests and their responses are included for reference.

The screenshots of the Postman interface (version 10.13.4) used throughout the guide are from a Mac OS X version. While it shouldn’t look/behave too differently in other Operating Systems, some steps in the guide might require minor adaptations depending on the Operating System type and/or Postman version.

The guide uses curl for REST API examples and jq for formatting the JSON responses, and Postman. Install these applications on your local if you haven’t already.

NOTE: The guide assumes its readers have administrative access to an Identity Cloud tenant.

About the ForgeRock Identity Cloud Postman collection

Examples of REST APIs used for common tasks in Identity Cloud such as user management, authentication, and authorization are grouped in a Postman collection.

Different components are responsible for various functionalities of Identity Cloud. Authentication and authorization in Identity Cloud are handled by the Access Management (AM) component, User Management is handled by Identity Management (IDM). When working on the Postman Collections, notice the presence of “/am” or “/openidm” in some of the HTTP endpoints.

To understand the Identity Cloud Rest API, it is a good practice to study the method, parameters (params), headers, body and the URI of each HTTP request example.

An Identity Cloud tenant has two realms namely alpha and bravo. A realm is a basic unit of administration in an Identity Cloud tenant. Each realm can have its own set of Identities to manage, authentication journeys, password policies, etc. The Postman Collection examples operate on the alpha realm of the Identity Cloud tenant. By changing the realm name in HTTP endpoints, the examples can be made to work on the Bravo realm as well.

Preparing the ForgeRock Identity Cloud Postman collection environment ~ 5min

1. Download the Identity Cloud Postman collection from the ForgeRock Identity Cloud official documentation.

2. In Postman, open your workspace and click Import.

3. Paste the URL for ForgeRock Identity Cloud Postman Collection.
   

   

4. Click > on the left side of the Collection name to expand various groups.

   

   Each group expands to show example REST calls that consume functionalities exposed by various Identity Cloud REST endpoints. For example, the Intelligent Access folder groups REST calls to authenticate a user with Identity Cloud, get the user’s session details etc.

   

5. To start using the ForgeRock Identity Cloud Postman Collection, create a user in Identity Cloud:

   a. In a supported browser, log into your Identity Cloud Admin UI.

   b. In the alpha realm, go to Identities > Manage > + New Alpha realm - User.

   

6. Create a new Identity Cloud user using the following information:

   • Username: postmanAdminUser
   • First Name: PostmanAdmin
   • Last Name: User
   • Email Address: postmanAdminUser@example.com
   • Password: Rock5tar10$

7. On the postmanAdminUser edit profile page, click on Authorization Roles > + Add Authorization Roles.

   

8. Add the following Authorization Roles and click Save.

   • openidm-authorized
   • openidm-admin

9. In Postman, go to ForgeRock Identity Cloud Collection > Variables. See Variables for further information.

10. Change the current values for the variables in the table below to reflect the Identity Cloud environment specific details. For example, replace the value of the PlatformUrl variable from <tenant-env-fqdn> to the Identity Cloud tenant URL being used.

    To get the cookieName of your Identity Cloud tenant, log in to the Identity Cloud Admin UI, click on Tenant settings on the top right corner of the administrator dashboard and look for Global settings > Cookie.

platformUrl	Replace <tenant-env-fqdn> with Identity Cloud tenant URL
amUrl	Replace <tenant-env-fqdn> section with Identity Cloud tenant URL
idmUrl	Replace <tenant-env-fqdn> section with Identity Cloud tenant URL
IDCloudAdminUsername	Identity Cloud tenant administrator
IDCloudAdminPassword	Identity Cloud tenant administrator password
cookieName	cookieName in your ForgeRock Identity Cloud Tenant settings.
postmanClientSecret	postmanClientSecret
postmanAdminUsername	postmanAdminUser
postmanAdminPassword	Rock5tar10$
postmanDemoPassword	p0stmanD3moPas$word

11. Click Save.

The environment is now ready to run the ForgeRock Identity Cloud Postman Collection.

Further reading

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

• Part 2 - Prerequisites
• Part 3 - Intelligent Access
• Part 4 - User self-service
• Part 5 - Session management
• Part 6 - Identity profiles & OAuth 2.0 flows
• Part 7 - Managed identities
• Part 8 - Auditing and monitoring

Other useful links:

• Postman collection
• REST API
• Configuring the ForgeRock Identity Cloud Postman Collection (Part 1 of 3) - All about Postman variables
• Identity Cloud Postman collection