OpenDJ: REST to LDAP, part 3

OpenDJ Community Logo Since my last post on this topic, there have been some important changes in RESTful access to OpenDJ.

Here’s a short list.

  • Jean-Noël added an HTTP connection handler to OpenDJ directory server.

    All you have to do is enable the HTTP connection handler, and you can start using the RESTful API without installing any other software.

  • Matt added authentication support to let you do:
    • HTTP Basic authentication (with different ways to map the user ID to an entry)
    • OpenIDM-style authentication (using headers, by default X-OpenIDM-Username and X-OpenIDM-Password)
    • Something else if you want to write your own Servlet Filter to handle authentication
  • Matt added support for deleting resources.
  • Matt renamed the REST API HTTP query request parameter _filter to _queryFilter (which is more consistent with _queryId and _queryExpression in OpenIDM).

HTTP Connection Handler

Enable the HTTP connection handler after installing OpenDJ.

$ dsconfig set-connection-handler-prop \
--hostname opendj.example.com --port 4444 \
--bindDN "cn=Directory Manager" --bindPassword password \
--handler-name "HTTP Connection Handler" \
--set enabled:true --no-prompt

Once you have enabled the HTTP connection handler, OpenDJ listens on port 8080 by default. The paths start at the root context. (As of this writing, April 5, 2013, you also need to authenticate for GET.)

$ curl --user bjensen:hifalutin \

http://opendj.example.com:8080/users/bjensen?_prettyPrint=true

{
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "bjensen@example.com",
  "displayName" : "Barbara Jensen",
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}

You configure the HTTP connection handler in the same way you configure the REST LDAP gateway, by using a JSON format configuration file. By default, the file is /path/to/OpenDJ/config/http-config.json.

Authentication Support

Matt implemented authentication support a couple of weeks ago. Right now the docs are out of sync with the trunk.  I am waiting on an enhancement, OPENDJ-827 (Simplify Rest2LDAP’s authentication configuration model), before updating the appendix on configuration.

In the meantime, if you want to start reconfiguring authentication now, read the comments the configuration file.

Deleting Resources

As of this writing, April 5, 2013, you can delete resources through the gateway, though not yet through the HTTP connection handler. That is likely to change soon.

By default, the configuration has "useSubtreeDelete" : true, so if you try to delete as a user without access rights to perform a tree delete, you can get an error because that control is not in the ACIs.

$ curl --request DELETE \
--user kvaughan:bribery \

http://opendj.example.com:8080/rest2ldap/users/bjensen?_prettyPrint=true

{
  "code" : 500,
  "reason" : "Internal Server Error",
  "message" : "Unavailable Critical Extension: The request control with Object Identifier (OID) \"1.2.840.113556.1.4.805\" cannot be used due to insufficient access rights"
}

If you set "useSubtreeDelete" : false in the configuration file, opendj-rest2ldap-servlet.json and reload the gateway, then you can use delete for individual resources.

$ curl --request DELETE \
--user kvaughan:bribery \

http://opendj.example.com:8080/rest2ldap/users/bjensen?_prettyPrint=true

{
  "_rev" : "000000007f413b85",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
  },
  "_id" : "bjensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Barbara"
  },
  "userName" : "bjensen@example.com",
  "displayName" : "Barbara Jensen",
  "manager" : [ {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  } ]
}

As you can see, the delete returns the resource you removed.

You can also use the resource revision in an If-Match header to assert that the resource to delete is in fact the same version of the resource that you expect.

To try this, get the revision.

$ curl --user kvaughan:bribery \
"http://opendj.example.com:8080/rest2ldap/users/ajensen?_fields=_rev&_prettyPrint=true"
{
  "_rev" : "000000002222a818"
}

If you have the wrong revision for the current resource and use the assertion, the delete fails.

$ curl --request DELETE \
--header "If-Match: wrong-rev" \
--user kvaughan:bribery \

http://opendj.example.com:8080/rest2ldap/users/ajensen?_prettyPrint=true

{
  "code" : 412,
  "reason" : "Precondition Failed",
  "message" : "Assertion Failed: Entry uid=ajensen,ou=People,dc=example,dc=com cannot be removed because the request contained an LDAP assertion control and the associated filter did not match the contents of the entry"
}

If you have the right revision, the delete can complete successfully.

$ curl --request DELETE \
--header "If-Match: 000000002222a818" \
--user kvaughan:bribery \

http://opendj.example.com:8080/rest2ldap/users/ajensen?_prettyPrint=true

{
  "_rev" : "000000007eea3869",
  "schemas" : [ "urn:scim:schemas:core:1.0" ],
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 7892",
    "emailAddress" : "ajensen@example.com"
  },
  "_id" : "ajensen",
  "name" : {
    "familyName" : "Jensen",
    "givenName" : "Allison"
  },
  "userName" : "ajensen@example.com",
  "displayName" : "Allison Jensen",
  "manager" : [ {
    "_id" : "kwinters",
    "displayName" : "Kelly Winters"
  } ]
}

More to come…

About these ads

1 Comment

Filed under Directory Services and LDAP

One response to “OpenDJ: REST to LDAP, part 3

  1. Pingback: OpenDJ: REST to LDAP, part 4 | Margin Notes 2.0

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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