top of page


  • Debasis Dwivedy

Communicating with ForgeRock Directory Service over REST

Author: Debasis Dwivedy

About Debasis

This is my first blog for Midships after recently joining. I am a Senior Kubernetes & IDAM Engineer at Midships with 10+ years of hands-on experience undertaking complex technology delivery, IAM and security/privacy

For any feedback, queries or other topics of interest, feel free to contact me at


The Challenge

Recently I came across an interesting problem statement where a customer journey required an authentication tree to create users/devices on ForgeRock Directory Services (DS) within a different OU (but the same DN).

Following an investigation, I found that ForgeRock does not have a standard node to CREATE/UPDATE/DELETE entries directly from an authentication tree. Instead, ForgeRock provides an LDAP QUERY NODE to query entities across OU’s within the baseDN, but there is no node for CREATE/UPDATE/DELETE operations.

The Solution

We identified three approaches to solve this:

  • Use ForgeRock IDM

  • Use AM user Self Service functionality

  • Communicate with ForgeRock DS over REST

We ruled out using ForgeRock IDM, as using this only to perform CRUD options did not seem to be an appropriate use of IDM as IDM is not used to support any other services across the estate. The use of IDM in this scenario did not align with Midships’ principle of keeping architecture simple (where possible).

AM User Self Service functionality is not appropriate as this is being phased out soon by ForgeRock. It also did not solve all our business requirements. We not only need to register a user but also register their device and update it when need be.

This leaves us with the third approach to register a user and their device using ForgeRock DS HTTP/HTTPS connection handlers over REST protocol.


ForgeRock DS provides us the mechanism to communicate with it using the following communication protocol using connection handlers configured during DS setup process or afterwards using dsconfig:



Setting up a connection handler looks as follows:

dsconfig  create-connection-handler  \
--hostname localhost  \
--port 4444  \
--bindDN uid=admin \ 
--bindPassword **** \ 
--handler-name HTTPS  \
--type http  \
--set enabled:true \ 
--set listen-port:8443  \
--set use-ssl:true  \
--set key-manager-provider:PKCS12  \
--set trust-manager-provider:"JVM Trust Manager"  \
--usePkcs12TrustStore /path/to/opendj/config/keystore  \
--trustStorePasswordFile /path/to/opendj/config/  \

For secure communication and production environment, we only set LDAPS and HTTPS connection handlers. After setting up the connection handler we must enable the Rest2Ldap interface to communicate with DS. Below mentioned are the steps that we followed to reach our objective:

Create Mapping

To communicate with DS using REST and to perform CRUD operations we must first define the mapping between the LDAP attributes and HTTP fields taking user input. A Rest2ldap mapping file defines how JSON resources map to LDAP entries. The default mapping file is /path/to/opendj/config/rest2ldap/endpoints/api/example-v1.json.

Taking the sample JSON file mentioned above we created two mapping files : one for OU=people and OU=mobileDevices. Below are the snippets the JSON files:

Download TXT • 9KB

After creating the mapping files, place those file on DS server as below:

· OU=people: /path/to/ds/config/rest2ldap/endpoints/people/people.json

· OU=mobileDevices


Create/Enable HTTP Endpoint

Create and enable the HTTP endpoint if not already created as below. This tells the DS where to pick up the mapping files from and name of the endpoint.

Create and Enable HTTP Endpoint
Download TXT • 684B


Now we are ready to test our configuration. We use curl to communicate with ForgeRock DS.

Mentioned below are the queries that we used to test CRUD operations:

Download TXT • 1KB

Now we are ready to use ForgeRock AM Authentication Trees’s scripted nodes to perform our CRUD operations on DS over REST.


Our next blog will go through the steps that need to be taken to configure and use ForgeRock AM scripted no/ to use REST to access resources.

Other documents for reference

61 views0 comments


bottom of page