PingDS

Install an HDAP gateway

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

hdap

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:

    $ mv DS-hdap-servlet-7.5.2.war hdap.war
$ cp hdap.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 default configuration connects to localhost:1389. When you set up DS for evaluation, port 1389 is a cleartext port. The default password policies allow simple binds for authentication only on secure connections. To let the gateway authenticate to DS on a cleartext port, update the relevant password policies to set require-secure-authentication:false.

      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. Find examples in Trust certificates.

    • The proxy user LDAP account performs proxied authorization. In the default gateway configuration, the proxy user is the default directory superuser, uid=admin.

      In a DS directory server set up for evaluation, the directory superuser can’t act as the proxy user by default. The account with simple bind credentials cn=My App,ou=Apps,dc=example,dc=com and password can act as a proxy user. If you keep the directory superuser as the proxy user, adapt the instructions in proxied authorization to grant proxied authorization access and privileges to the directory superuser.

    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. Find more information about log level definitions in 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.

    Learn more in the container documentation.

  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

  1. Set up a DS directory server for evaluation.

  2. Install and configure the HDAP gateway.

  3. 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'
    Output
    {
  "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
  "_rev" : "<revision>",
  "cn" : [ "Barbara Jensen", "Babs Jensen" ]
}
    json

You have demonstrated the HDAP gateway works as expected.