Introduction to ForgeRock REST APIs

[lucy.billington]

Overview

One of the unique features of the ForgeRock identity solution is that all platform components share a single, easy-to-use RESTful web API. This is known as the ForgeRock Common REST API framework.

The ForgeRock Common REST API framework provides consistent ways to access web resources and collections of resources. This makes it easy for implementers and deployers to solve business-critical identity management-related problems quickly, avoiding the need for developers to learn more complex Java APIs.

REST APIs are available to configure ForgeRock services, including but not limited to:

• Authentication (adding user journeys and nodes)
• Authorization (creating policies, conditions, rules)
• OAuth2/OIDC (client registration and management)
• SAML2 (entity creation and management)
• Identities (creation, management, lifecycle)

Instantiation of services via REST APIs is also possible for services, including but not limited to:

• Authentication (logging in, passwordless, OTP, MFA, etc.)
• Authorization (evaluating user-to-resource access)
• Token exchange services
• Federation
• Triggering actions, such as starting synchronization or validating sessions

In addition, all configurations in ForgeRock products can be set through REST.

ForgeRock Common REST API framework behaviors

The ForgeRock Common REST API framework works across the ForgeRock platform and implements the following behaviors:

• REST resources: Servers generally return JSON-format resources, although resource formats can depend on the specific implementation. See Common REST resources for further details.

• REST verbs: The common REST API uses the verbs Create, Read, Update, Delete, Patch, Action, and Query (sometimes known as CRUDPAQ). See REST verbs for further details.

• REST parameters: Common REST reserved query string parameter names start with an underscore (_). They include but are not limited to: _action, _api, _crestapi, _fields, _mimeType, _pageSize, _pagedResultsCookie, _pagedResultsOffset, _prettyPrint, _queryExpression, _queryFilter, _queryId, _sortKeys, _totalPagedResultsPolicy. See Common REST parameters for further details.

• REST extension points: The action verb is the main vehicle for extensions. For example, /users?_action=create. See Common REST extension points for further details.

• REST API descriptor: You can generate a descriptor of the REST API to provide API reference documentation specific to your deployment, and the final descriptor can be published alongside your production deployment. See Common REST API documentation for further details.

• REST API versions: REST API versioning is available at some endpoints to ensure compatibility between releases. See REST API versions for further details.

• Custom endpoints: Custom REST endpoints are available in some products, allowing you to run arbitrary scripts through the REST API. See Create custom endpoints to launch scripts for further details.

• REST endpoints for admin and end-user UIs: Complete UI customization, or integration with your existing portals, can be achieved by invoking the same REST APIs as ForgeRock’s supplied UI.

Not all ForgeRock components and products implement the common REST behaviors exactly as described above. For details on how REST behaviors are implemented in the various ForgeRock components (Identity Cloud, AM, IDM, DS and IG), see the product documentation referenced in the sections below:

• Identity Cloud and REST
• AM and REST
• IDM and REST
• DS and REST
• IG and REST

Postman collections

You can use applications such as Postman to create, run, and manage collections of REST calls. Alternatively, you can use the curl command line utility, included with most operating systems.

To help you to get started with ForgeRock REST APIs, ForgeRock provides Postman collections that contain example requests grouped into features. Postman collections are available for Identity Cloud, AM and IDM delegated administration.

Identity Cloud and REST

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

ForgeRock Identity Cloud implements the ForgeRock Common REST API, with the exception of the elements described in Common REST and Identity Cloud.

You can authenticate to Identity Cloud REST API using different methods for:

• Read-only operations like monitoring and logging.
• Access management operations like setting up user journeys or policies.
• Identity management operations or write operations like configuring user profiles, roles, or assignments.

Access management REST endpoints

REST API endpoints for Identity Cloud access management are defined in the following documentation:

• Authenticate using REST
• Request policy decisions over REST
• OAuth 2.0 endpoints
• OAuth 2.0 administration endpoints
• OpenID Connect 1.0 endpoints
• Server configuration

Identity management REST endpoints

REST API endpoints for Identity Cloud identity management are defined in the following documentation:

• Server configuration
• Managed users
• Managed groups
• Managed organizations
• System objects
• Internal objects
• Feature enablement
• Schedules
• Scanning tasks
• Reconciliation operations
• Synchronization service
• Scripts
• Privileges
• Email
• Bulk import
• Server state

Further reading

• REST API overview
• REST API for access management
• REST API for identity management
• Postman collection

Training videos:

• Getting Started: Identity Cloud REST APIs

AM and REST

ForgeRock Access Management (AM) offers a REST API for:

• Authentication and session logout
• Authorization and policy management
• Filtering and sorting
• Identity and realm management
• Logging (using the REST-based common audit service)
• Token attribute retrieval and token validation
• OAuth 2.0, OpenID Connect 1.0, and UMA 2.0
• Retrieving server information
• User self-service

The REST API is also available for provisioning users into AM, although this should be avoided in favor of IDMs provisioning endpoints.

AM REST endpoints

REST API endpoints for AM are defined in the following documentation:

• Authenticate over REST
• Manage sessions over REST
• Policies over REST, Policy sets over REST, Resource types over REST, and Policy set application types over REST
• Request policy decisions over REST
• OAuth 2.0 endpoints
• OAuth 2.0 administration REST endpoints
• OpenID Connect 1.0 endpoints
• Retrieve forgotten usernames, Reset forgotten passwords, and Register a user
• Configure identities and realms over REST
• Manage scripts (REST)
• Capture troubleshooting information
• Consume REST STS instances and Query, validate, and cancel tokens
• Reset registered devices over REST

Further reading

• REST API - AM7.2
• REST API endpoints
• How do I use the Postman collections that are provided for AM (All versions)?

IDM and REST

The ForgeRock Common REST API framework exposes all IDM functionality via REST. This allows for automated control and configuration of the solution. A good illustration of this is the administrator UI, which is a layer that calls the same REST APIs that are available to you externally to configure the product; whatever you can do manually as an administrator by changing configuration files you can also do securely via REST.

The REST API can be used for accessing managed objects, system objects, workflows, and some elements of the system configuration. Typical operations are CRUD operations (Create, Read, Update, Delete) on users, roles, or custom-managed objects, as well as more advanced PAQ operations (Patch, Action, Query). REST requests are also available to manage workflows and tasks.

IDM REST endpoints

REST API endpoints for IDM are defined in the following documentation:

• Server configuration
• Managed users
• Managed organizations
• System objects
• Internal objects
• Schedules
• Scanning tasks
• Audit logs
• Reconciliation operations
• Synchronization service
• Scripts
• Privileges
• Email
• File upload
• Bulk import
• Server state
• Social identity providers
• Workflows

Further reading

• REST API reference
• REST and IDM
• REST API structure

DS and REST

ForgeRock Directory Services (DS) REST APIs are based on the ForgeRock Common REST API framework. They can expose directory data as JSON resources over HTTP to REST clients, providing easy access to directory data for developers who are not familiar with LDAP.

This is achieved with a REST to LDAP gateway that can be embedded or used standalone.

REST clients can do just about anything an LDAP client can do with directory data. Also, the REST to LDAP gateway can be deployed remotely, as a gateway in a DMZ for example, or it can be embedded in DS, depending on your requirements.

Further reading

• DS REST APIs
• Configuration examples
• REST to LDAP reference

IG and REST

With ForgeRock Identity Gateway (IG), you can create and edit routes through Common REST API commands. This allows you to read, add, delete, and edit routes on IG without manually accessing the file system.

In addition, the User-Managed Access (UMA) service (UmaService) in IG uses the Common REST API to manage the sharing of resource sets.

Further Reading

• About Common REST
• Create and edit routes through Common REST
• UmaService

[anishetty]

Hello.

Thank you for the detailed post.

However, I couldn’t find the Postman collection for AM in the link provided. Could you please let me know where to find it?

[lucy.billington]

Hello

Thank you for your feedback. We don’t provide a single Postman collection for AM like we do for Identity Cloud. However, if you click the links under “Postman collections in the Knowledge Base” in this article you will find various Postman collections for AM. I hope that helps :)