7.2. Authenticating Over REST

When you first try to get a resource that you can read as an LDAP entry with an anonymous search, you might be surprised that you must authenticate. 

$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "code" : 401,
  "reason" : "Unauthorized",
  "message" : "Unauthorized"
}

HTTP status code 401 tells your HTTP client that the request requires user authentication. You can change this behavior by setting the HTTP connection handler property, authentication-required, to false. 

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

Out of the box both the HTTP Connection Handler and also the REST LDAP gateway are configured to allow HTTP Basic authentication and HTTP header based authentication in the style of OpenIDM. The authentication mechanisms translate HTTP authentication to LDAP authentication on the directory server side.

When you install OpenDJ either with generated sample user entries or with data from Example.ldif, the relative distinguished name attribute for the sample user entries is the user ID (uid) attribute. For example, the DN and user ID for Babs Jensen are as follows. 

dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen

Given this pattern in the user entries, the default REST to LDAP configuration assumes that the user name on the HTTP side is the value of the user ID, and that user entries can be found under ou=People,dc=example,dc=com. In other words, Babs Jensen authenticates as bjensen (password: hifalutin) over HTTP. This is mapped for an LDAP bind to the bind DN uid=bjensen,ou=People,dc=example,dc=com.

With HTTP Basic authentication, it looks like this.

$ curl
 --user bjensen:hifalutin
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

Or, using the HTTP Basic username:password@ form in the URL, it looks like this. 

$ curl
http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

With HTTP header based authentication, it looks like this.

$ curl
 --header "X-OpenIDM-Username: bjensen"
 --header "X-OpenIDM-Password: hifalutin"
 http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
  "_rev" : "0000000016cbb68c",
  ...
}

If your directory data are laid out differently, or if your user names are email addresses rather than user IDs for example, then you must update the configuration in order for authentication to work.

The REST LDAP gateway can also translate HTTP user name and password authentication to PLAIN SASL authentication on the LDAP side. Moreover, the gateway can fall back to proxied authorization as necessary, using a root DN authenticated connection to LDAP servers. See REST LDAP Configuration for details on all configuration choices.