Directory Services 7.4.3

Install an HDAP gateway

The DS HDAP gateway web application translates HTTP requests in LDAP requests:

hdap

The interface stability for HDAP is Technology Preview. Technology previews offer access to new technology ForgeRock doesn’t support yet. They may be functionally incomplete and subject to change without notice. For details, refer to Interface stability.

REST to LDAP remains supported as documented for DS 7.3. The interface stability for REST to LDAP is Deprecated in favor of HDAP for future applications.

The HDAP gateway functions as a web application in a web application container. It runs independently of the LDAPv3 directory service. The LDAPv3 directory service must support proxied authorization. In particular, this means you can use the HDAP gateway with current and previous versions of DS.

Installation

  1. Review the requirements for installation to verify the HDAP gateway supports your web application container.

  2. Deploy the .war file according to the instructions for your web application container; for example:

    $ cp DS-hdap-servlet-7.4.3.war /path/to/tomcat/webapps/

    If you use Wildfly, you must unzip the .war file into the deployment directory.

  3. Edit the configuration in the deployed gateway web application:

    WEB-INF/classes/config.json

    This file defines how the HDAP gateway connects to and interacts with LDAP directory servers.

    At minimum, set the directory server hostnames, port numbers, and proxy user credentials. The proxy user LDAP account performs proxied authorization. In a DS directory server set up for evaluation, the account with simple bind credentials cn=My App,ou=Apps,dc=example,dc=com and password can act as a proxy user.

    When connecting to the remote directory service over LDAPS or LDAP and StartTLS (recommended), configure the gateway client-side trust manager to trust the server certificates. For help, refer to the examples showing how to trust DS server certificates.

    WEB-INF/classes/logging.properties

    This file defines logging properties when you run the gateway in Apache Tomcat.

  4. (Optional) Adjust the log level.

    At the default log level of INFO, the HDAP gateway logs messages about HTTP requests. For log level definitions, refer to java.util.logging.Level.

    If the HDAP gateway runs in Apache Tomcat, edit the logging.properties file. Otherwise, set the log level as described in the container documentation.

  5. (Recommended) Configure the web application container to use HTTPS for secure connections to the gateway.

    Refer to the container documentation for details.

  6. Restart the HDAP gateway or the web application container.

    The gateway reloads its configuration.

  7. Verify the directory service is up and the gateway connects correctly.

Verification

Install and configure the HDAP gateway before following these steps:

  1. Set up a DS directory server for evaluation.

  2. Read Babs Jensen’s resource through the gateway.

    If necessary, adjust the protocol (https), port (8443), and base path (/hdap) for your configuration:

    $ curl \
 --user dc=com/dc=example/ou=People/uid=bjensen:hifalutin \
 'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=cn&_prettyPrint=true'
{
  "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
  "_rev" : "<revision>",
  "cn" : [ "Barbara Jensen", "Babs Jensen" ]
}

You have demonstrated the HDAP gateway works as expected.