Directory Services 7.4.3

Learn HDAP

ForgeRock Directory Services let you access LDAP data over HTTP using HTTP Directory Access Protocol (HDAP) APIs that transform HTTP operations into LDAP operations.

The interface stability for HDAP is Technology Preview. Technology previews offer access to new technology ForgeRock doesn’t support yet. They may be functionally incomplete and subject to change without notice. For details, refer to Interface stability.

REST to LDAP remains supported as documented for DS 7.3. The interface stability for REST to LDAP is Deprecated in favor of HDAP for future applications.

Before you try the examples, follow the instructions in Install DS.

Prepare

Get the deployment CA certificate to trust the server:

$ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile ca-cert.pem
bash

Create

Use HDAP to create a user resource:

$ curl \
--request POST \
--cacert ca-cert.pem \
--user :password \
--header 'Content-Type: application/json' \
--data '{
  "_id" : "dc=com/dc=example/ou=People/uid=newuser",
  "objectClass" : [ "person", "inetOrgPerson", "organizationalPerson", "top" ],
  "cn" : [ "New User" ],
  "givenName" : [ "New" ],
  "mail" : [ "newuser@example.com" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=bjensen" ],
  "sn" : [ "User" ],
  "telephoneNumber" : [ "+1 408 555 1212" ],
  "uid" : [ "newuser" ]
}' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People?_prettyPrint=true'

{
  "_id" : "dc=com/dc=example/ou=People/uid=newuser",
  "objectClass" : [ "person", "inetOrgPerson", "organizationalPerson", "top" ],
  "cn" : [ "New User" ],
  "givenName" : [ "New" ],
  "mail" : [ "newuser@example.com" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=bjensen" ],
  "sn" : [ "User" ],
  "telephoneNumber" : [ "+1 408 555 1212" ],
  "uid" : [ "newuser" ]
}
bash

  • The command makes a secure connection to the server using HTTPS.

  • The user performing the HTTP POST is the directory superuser.

    The default authorization mechanism for HTTP access is HTTP Basic authentication. The superuser’s HTTP user ID, admin, is mapped to the LDAP DN, . HDAP uses the DN and password to perform a simple LDAP bind for authentication. The directory uses its LDAP-based access control mechanisms to authorize the operation.

  • The successful response is the JSON resource that the command created.

    Fields names starting with an underscore like _id are reserved. For details, refer to HDAP API reference.

For additional details, refer to HDAP API reference and Create.

Read

Use HDAP to read a user resource:

$ curl \
--request GET \
--cacert ca-cert.pem \
--user dc=com/dc=example/ou=People/uid=bjensen:hifalutin \
--header 'Content-Type: application/json' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=newuser?_prettyPrint=true'

{
  "_id" : "dc=com/dc=example/ou=People/uid=newuser",
  "_rev" : "<revision>",
  "objectClass" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "cn" : [ "New User" ],
  "givenName" : [ "New" ],
  "mail" : [ "newuser@example.com" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=bjensen" ],
  "sn" : [ "User" ],
  "telephoneNumber" : [ "+1 408 555 1212" ],
  "uid" : [ "newuser" ]
}
bash

Babs Jensen authenticates for this HTTP GET request. If no credentials are specified, the response is the HTTP 401 Unauthorized:

{"code":401,"reason":"Unauthorized","message":"Invalid Credentials"}
json

In other words, the HTTP Basic authorization mechanism requires authentication even for read operations.

For additional details, refer to HDAP API reference and Read. You can also query collections of resources, as described in Query.

Update

Use HDAP to update a user resource:

$ curl \
--request PUT \
--cacert ca-cert.pem \
--user :password \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--data '{
  "cn" : [ "Updated User" ],
  "givenName" : [ "Updated" ],
  "mail" : [ "updated.user@example.com" ],
  "telephoneNumber" : [ "+1 234 567 8910" ]
}' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=newuser?_prettyPrint=true'

{
  "_id" : "dc=com/dc=example/ou=People/uid=newuser",
  "objectClass" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "cn" : [ "Updated User" ],
  "givenName" : [ "Updated" ],
  "mail" : [ "updated.user@example.com" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=bjensen" ],
  "sn" : [ "User" ],
  "telephoneNumber" : [ "+1 234 567 8910" ],
  "uid" : [ "newuser" ]
}
bash

HDAP versions resources with revision numbers. A revision is specified in the resource’s _rev field.

The --header "If-Match: *" tells HDAP to replace the resource regardless of its revision. Alternatively, set --header "If-Match: revision" to replace the resource only if its revision matches.

For additional details, refer to HDAP API reference and Update. You can also patch resources instead of replacing them entirely. Refer to Patch.

Delete

Use HDAP to delete a user resource:

$ curl \
--request DELETE \
--cacert ca-cert.pem \
--user :password \
--header 'Content-Type: application/json' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=newuser?_prettyPrint=true'

{
  "_id" : "dc=com/dc=example/ou=People/uid=newuser",
  "_rev" : "<revision>",
  "objectClass" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ],
  "cn" : [ "Updated User" ],
  "givenName" : [ "Updated" ],
  "mail" : [ "updated.user@example.com" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=bjensen" ],
  "sn" : [ "User" ],
  "telephoneNumber" : [ "+1 234 567 8910" ],
  "uid" : [ "newuser" ]
}
bash

For additional details, refer to HDAP API reference and Delete.