OpenDJ: REST to LDAP, part 5

OpenDJ community logo If you have been reading about REST to LDAP here, then you might be wondering why there is still nothing said about authentication over HTTP. In fact, both the HTTP Connection Handler and the REST LDAP gateway Servlet have been able to do HTTP Basic authentication and HTTP header based authentication in the style of OpenIDM for some time.

It’s pretty much what you’d expect. Yet, when you first set up either the connection handler or the gateway, and try to get a resource that you can read as an LDAP entry with an anonymous search, you might be surprised at the need to authenticate.

$ curl
  "code" : 401,
  "reason" : "Unauthorized",
  "message" : "Unauthorized"

The authentication mechanisms configured for the connection handler or the gateway translate HTTP authentication to LDAP authentication on the directory server side. By default, they take the user name from HTTP authentication, and map that to an LDAP user ID to find the user’s entry in the directory in order to get the DN for the LDAP bind. Therefore, a user name like bjensen maps to an entry uid=bjensen,ou=People,dc=example,dc=com.

HTTP Basic authentication then looks like one of the following.

$ curl --user bjensen:hifalutin


$ curl

HTTP header based authentication looks like this.

$ curl \
 --header "X-OpenIDM-Username: bjensen" \
 --header "X-OpenIDM-Password: hifalutin" \

There is more to the story. For example, the REST LDAP gateway can be set up to do PLAIN SASL authentication on the directory server side. It can also do/fall back to authentication as Directory Manager and then use proxied authorization. And of course the mappings are configurable.

My aim is to wrap this up for the next release in the OpenDJ in-progress docs, looking forward to RESTful access as one of the most important deliveries in the short term of the OpenDJ road map.

Get a nightly build, and let us know what you find when trying it out.


2 thoughts on “OpenDJ: REST to LDAP, part 5

  1. Hi Mark,

    thank you for the nice tutorial.
    I’m trying to see now if is possible to define nested REST resources in rest2ldap.json config file. Something like: “/group/{id}/role/{id}” where /group and /role resources are both “groupOfUniqueNames”.
    I’ve spent some time on this but not with success. Do you have some idea/examples how I can achieve that ?

    Thank you.
    Best regards,

    1. Up to OpenDJ 3.5, there wasn’t a way to do this.

      In OpenDJ 3.5 and later, including current nightly builds, there’s a notion of “subResources” that’s used in the default example configuration:

              // This resource represents the entry point into the user/group API. It only defines sub-resources and
              // does not have any properties itself. Template variables are permitted within the URL and DN templates.
              "example-v1": {
                  "subResources": {
                      "users": {
                          "type": "collection",
                          "dnTemplate": "ou=people,dc=example,dc=com",
                          "resource": "frapi:opendj:rest2ldap:user:1.0",
                          "namingStrategy": {
                              "type": "clientDnNaming",
                              "dnAttribute": "uid"
                      "groups": {
                          "type": "collection",
                          "dnTemplate": "ou=groups,dc=example,dc=com",
                          "resource": "frapi:opendj:rest2ldap:group:1.0",
                          "namingStrategy": {
                              "type": "clientDnNaming",
                              "dnAttribute": "cn"

      The “subResources” property described in the OpenDJ Reference, Table A.1. Resource Type Properties, but I haven’t written any examples of the type you’re looking for. I’m sort of waiting for a fix for OPENDJ-3160 before documenting it further.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s