Communicating with ForgeRock Directory Service over REST
Author: Debasis Dwivedy
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 firstname.lastname@example.org
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.
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/keystore.pin \ --no-prompt
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:
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:
After creating the mapping files, place those file on DS server as below:
· OU=people: /path/to/ds/config/rest2ldap/endpoints/people/people.json
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.
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:
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