Guide to getting started quickly with ForgeRock® Directory Services software.

Searching the directory is like searching for a phone number in a phone book. You can look up a subscriber's phone number because you know the subscriber's last name. In other words, you use the value of an attribute to find entries that have attributes of interest.

When looking up a subscriber's entry in a phone book, you need to have some idea where they live in order to pick the right phone book. For example, a Los Angeles subscriber cannot be found in the New York phone book. In an LDAP directory, you need to know at least the base DN to search under.

For this example, assume you know a user's full name, Abagail Abadines, and that Abagail's entry is under the base DN dc=example,dc=com. You want to look up Abagail's email and office location. The following command sends an appropriate LDAP search request to the server you installed:

$ ldapsearch \
 --hostname localhost \
 --port 1389 \
 --baseDn dc=example,dc=com \
 "(cn=Abagail Abadines)" \
 cn mail street l
dn: uid=user.6,ou=People,dc=example,dc=com
cn: Abagail Abadines
mail: user.6@example.com
street: 61394 Adams Street
l: Lynchburg

For additional examples, see "Searching the Directory" in the Developer's Guide.

When searching for LDAP entries as shown in "Search an LDAP Directory", you might get results without authenticating to the directory.

When modifying directory data, however, you must authenticate first. LDAP servers must know who you are to determine what you have access to.

Consider the following example, where Abagail chooses to modify the description on her own entry:

$ ldapmodify \
 --hostname localhost \
 --port 1389 \
 --bindDn uid=user.6,ou=People,dc=example,dc=com \
 --bindPassword password <<EOF
dn: uid=user.6,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: New description
EOF
# MODIFY operation successful for DN uid=user.6,ou=People,dc=example,dc=com

For additional examples, see "Modifying Entry Attributes" in the Developer's Guide. Also see "Changing Passwords" in the Developer's Guide.

Authorized users can modify attributes, and can also add and delete directory entries.

The following example adds a new user entry to the directory:

$ ldapmodify \
 --hostname localhost \
 --port 1389 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password <<EOF
dn: uid=newuser,ou=People,dc=example,dc=com
uid: newuser
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: New User
sn: User
ou: People
mail: newuser@example.com
userPassword: changeme
EOF
# ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com

For additional examples, see "Adding Entries" in the Developer's Guide.

The following example deletes the user added in "Add an LDAP Entry":

$ ldapdelete \
 --hostname localhost \
 --port 1389 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 uid=newuser,ou=People,dc=example,dc=com
# DELETE operation successful for DN uid=newuser,ou=People,dc=example,dc=com

Notice that the ldapdelete command specifies the entry to delete by its DN.

For additional examples, see "Deleting Entries" in the Developer's Guide.

When you configured an HTTP port at setup time, you enabled the DS server to respond to HTTP requests. However, you must make a further change to the server configuration to enable HTTP access to your directory data.

Because the default REST to LDAP mapping file is an example designed to work with sample data, it is not guaranteed to work with your data. As a result, the API to access your directory data is not enabled by default.

The following command enables the API to access directory data using the default example mapping file:

$ dsconfig \
 set-http-endpoint-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --endpoint-name /api \
 --set enabled:true \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
 --no-prompt

Like the status command you ran in "To Install DS Software", the dsconfig command authenticates using the directory superuser credentials. It uses a secure connection to the administration port. To trust the server's self-signed certificate, the command uses the server's own keystore as the truststore. It sends a configuration request to enable the /api endpoint, where the directory server exposes the HTTP API to access directory data.

In order to make updates to the directory, authorize a user to do so. The following example authorizes Abagail (user.6) to make changes to directory data:

$ ldapmodify \
 --hostname localhost \
 --port 1389 \
 --bindDn "cn=Directory Manager" \
 --bindPassword password <<EOF
dn: dc=example,dc=com
changetype: modify
add: aci
aci: (target="ldap:///dc=example,dc=com") (targetattr = "*")
 (version 3.0;acl "Abagail can update entries"; allow(all)
  userdn = "ldap:///uid=user.6,ou=People,dc=example,dc=com";)
EOF

With the API enabled, and Abagail authorized to make changes to the directory, use the API to create a user over HTTP as in the following example:

$ curl \
 --request POST \
 --user user.6:password \
 --header "Content-Type: application/json" \
 --data '{
  "_id": "newuser",
  "_schema":"frapi:opendj:rest2ldap:user:1.0",
  "contactInformation": {
    "telephoneNumber": "+1 408 555 1212",
    "emailAddress": "newuser@example.com"
  },
  "name": {
    "givenName": "New",
    "familyName": "User"
  },
  "displayName": ["New User"],
  "manager": {
    "_id": "user.6",
    "displayName": "Abagail Abadines"
  }
 }' \
 http://opendj.example.com:8080/api/users?_prettyPrint=true
{
  "_id" : "newuser",
  "_rev" : "<revision>",
  "_schema" : "frapi:opendj:rest2ldap:user:1.0",
  "_meta" : {
    "created" : "<timestamp>"
  },
  "userName" : "newuser@example.com",
  "displayName" : [ "New User" ],
  "name" : {
    "givenName": "New",
    "familyName": "User"
  },
  "manager" : {
    "_id" : "user.6",
    "displayName" : "Abagail Abadines"
  },
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  }
}

For additional details, see "Create" in the Developer's Guide and "Creating Resources" in the Developer's Guide.

The following example reads the user resource created in "Create a Resource":

$ curl \
 --request GET \
 --user user.6:password \
 --header "Content-Type: application/json" \
 http://opendj.example.com:8080/api/users/newuser?_prettyPrint=true
{
  "_id" : "newuser",
  "_rev" : "<revision>",
  "_schema" : "frapi:opendj:rest2ldap:user:1.0",
  "_meta" : {
    "created" : "<timestamp>"
  },
  "userName" : "newuser@example.com",
  "displayName" : [ "New User" ],
  "name" : {
    "givenName": "New",
    "familyName": "User"
  },
  "manager" : {
    "_id" : "user.6",
    "displayName" : "Abagail Abadines"
  },
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1212",
    "emailAddress" : "newuser@example.com"
  }
}

Notice that Abagail 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"}

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

For additional details, see "Read" in the Developer's Guide and "Reading a Resource" in the Developer's Guide. You can also query collections of resources as described in "Query" in the Developer's Guide and "Querying Resource Collections" in the Developer's Guide.

The following HTTP PUT request replaces the user resource created in "Create a Resource":

$ curl \
 --request PUT \
 --user user.6:password \
 --header "Content-Type: application/json" \
 --header "If-Match: *" \
 --data '{
  "_id": "newuser",
  "_schema":"frapi:opendj:rest2ldap:user:1.0",
  "contactInformation": {
    "telephoneNumber": "+1 234 567 8910",
    "emailAddress": "updated.user@example.com"
  },
  "name": {
    "givenName": "Updated",
    "familyName": "User"
  },
  "displayName": ["Updated User"],
  "manager": {
    "_id" : "user.6",
    "displayName" : "Abagail Abadines"
  }
 }' \
 http://opendj.example.com:8080/api/users/newuser?_prettyPrint=true
{
  "_id" : "newuser",
  "_rev" : "<revision>",
  "_schema" : "frapi:opendj:rest2ldap:user:1.0",
  "_meta" : {
    "created" : "<timestamp>"
  },
  "userName" : "newuser@example.com",
  "displayName" : [ "Updated User" ],
  "name" : {
    "givenName" : "Updated",
    "familyName" : "User"
  },
  "manager" : {
    "_id" : "user.6",
    "displayName" : "Abagail Abadines"
  },
  "contactInformation" : {
    "telephoneNumber" : "+1 234 567 8910",
    "emailAddress" : "updated.user@example.com"
  }
}

Resources are versioned using revision numbers. A revision is specified in the resource's _rev field. The --header "If-Match: *" ensures the resource is replaced, regardless of its revision. Alternatively, you can set --header "If-Match: revision" to replace only the expected revision of the resource.

For additional details, see "Update" in the Developer's Guide and "Updating Resources" in the Developer's Guide. You can also patch resources instead of replacing them entirely. See "Patch" in the Developer's Guide and "Patching Resources" in the Developer's Guide.

The following HTTP DELETE request deletes the user resource updated in "Update a Resource":

$ curl \
 --request DELETE \
 --user user.6:password \
 --header "Content-Type: application/json" \
 http://opendj.example.com:8080/api/users/newuser?_prettyPrint=true
{
  "_id" : "newuser",
  "_rev" : "<revision>",
  "_schema" : "frapi:opendj:rest2ldap:user:1.0",
  "_meta" : {
    "created" : "<timestamp>"
  },
  "userName" : "newuser@example.com",
  "displayName" : [ "Updated User" ],
  "name" : {
    "givenName" : "Updated",
    "familyName" : "User"
  },
  "manager" : {
    "_id" : "user.6",
    "displayName" : "Abagail Abadines"
  },
  "contactInformation" : {
    "telephoneNumber" : "+1 234 567 8910",
    "emailAddress" : "updated.user@example.com"
  }
}

For additional details, see "Delete" in the Developer's Guide and "Deleting Resources" in the Developer's Guide.