Install a REST to LDAP Gateway

A REST to LDAP gateway web application translates an HTTP request into one or more LDAP requests. The translation depends on the specific REST to LDAP gateway configuration.

An identity mapper translates the user identity into an LDAP identity for the bind. For background information, see Identity Mappers.

Then the REST to LDAP mapping defines how the REST JSON resource corresponds to LDAP entries. The gateway handles the mapping configuration in the same way as an HTTP connection handler.

Figure 1. Requests Through a REST to LDAP Gateway

The REST to LDAP gateway functions as a web application in a web application container. The REST to LDAP gateway runs independently of the LDAPv3 directory service. As an alternative to the gateway, you can configure HTTP access to a directory server, as described in Configure HTTP User APIs.

You configure the gateway to access your directory service by editing configuration files in the deployed web application:

WEB-INF/classes/config.json: This file defines how the gateway connects to LDAP directory servers, and how user identities extracted from HTTP requests map to LDAP user identities.

For details, see Gateway LDAP Connections.
WEB-INF/classes/logging.properties: This file defines logging properties, and can be used when the gateway runs in Apache Tomcat.
WEB-INF/classes/rest2ldap/rest2ldap.json: This file defines which LDAP features the gateway uses.

For details, see Gateway LDAP Features.
WEB-INF/classes/rest2ldap/endpoints/api/example-v1.json: This file defines JSON resource to LDAP entry mappings.

You can edit this file, and define additional files for alternative APIs and versions of APIs. For details, see API Configuration.

Follow these steps to install the REST to LDAP gateway:

Prepare for installation.
Deploy the .war file according to the instructions for your web application container.

If you are using Wildfly, you must unzip the .war file into the deployment directory.
Edit the configuration files in the deployed gateway web application.

At minimum adjust the following configuration settings in WEB-INF/classes/config.json:
- primaryLDAPServers: Set the correct directory server hostnames and port numbers.
- authentication: Set the correct simple bind credentials.
  
  The LDAP account used to authenticate needs to perform proxied authorization, as described in Proxied Authorization.
  
  The default sample configuration works with generated example data, and with the sample data imported when you set up the directory server for evaluation, as shown in Install DS for Evaluation. If your data is different, then you must also change the JSON resource to LDAP entry mapping settings, as described in API Configuration.
  
  For details regarding the configuration, see REST to LDAP Reference.
  
  When connecting to a directory service over LDAPS or LDAP and StartTLS, you can configure the trust manager to use a file-based truststore for server certificates that the gateway should trust. This allows the gateway to validate server certificates signed, for example, by a certificate authority that is not recognized by the Java environment when setting up LDAPS or StartTLS connections.
  
  See Key Management for an example of how to use the Java keytool command to import a server certificate into a truststore file.
If necessary, adjust the log level.

Log levels are defined in java.util.logging.Level.

By default, the log level is set to INFO, and the gateway logs HTTP request-related messages. To have the gateway log LDAP request-related messages, set the log level to FINEST in one of the following ways:
1. If the REST to LDAP gateway runs in Apache Tomcat, edit WEB-INF/classes/logging.properties to set org.forgerock.opendj.rest2ldap.level = FINEST. For details on Tomcat’s implementation of the logging API, see Logging in Tomcat.
  
  Messages are written to CATALINA_BASE/logs/rest2ldap.yyyy-MM-dd.log.
2. If the REST to LDAP gateway runs in a different container, set the log level as described in the documentation.
  
  Messages are written to the container log.
Restart the REST to LDAP gateway or the web application container to make sure the configuration changes are taken into account.

Make sure that the directory service is up, and then check that the gateway is connecting correctly.

The following command reads Babs Jensen’s entry through the gateway to a directory server set up for evaluation, as shown in Install DS for Evaluation. In this example, the gateway is deployed under /rest2ldap:

$ curl \
 --user bjensen:hifalutin \
 --cacert ca-cert.pem \
 https://localhost:8443/rest2ldap/api/users/bjensen?_prettyPrint=true
{
  "_id" : "bjensen",
  "_rev" : "<revision>",
  "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0",
  "_meta" : { },
  "userName" : "bjensen@example.com",
  "displayName" : [ "Barbara Jensen", "Babs Jensen" ],
  "name" : {
    "givenName" : "Barbara",
    "familyName" : "Jensen"
  },
  "description" : "Original description",
  "contactInformation" : {
    "telephoneNumber" : "+1 408 555 1862",
    "emailAddress" : "bjensen@example.com"
  },
  "uidNumber" : "1076",
  "gidNumber" : "1000",
  "homeDirectory" : "/home/bjensen",
  "manager" : {
    "_id" : "trigden",
    "displayName" : "Torrey Rigden"
  }
}

If you generated example data, Babs Jensen’s entry is not included. Instead, try a generated user such as https://user.0:password@localhost:8443/rest2ldap/api/users/user.0.

Configure your web application container to use HTTPS for secure connections to the gateway.

See your web application container documentation for details.

DS 7.1.8

Install a REST to LDAP Gateway