How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I troubleshoot a DS (All versions) REST configuration?

Last updated Jun 14, 2021

The purpose of this article is to provide advice on troubleshooting DS REST configurations, include enabling logging for the REST interface.


DS provides access to REST clients using two different mechanisms:

  1. via the HTTP connection handler, which is included in DS but not enabled by default.
  2. via an external REST to LDAP (REST2LDAP) gateway servlet that runs in a web container such as Apache Tomcat™.

Troubleshooting what happens inside the REST interface can be difficult. This article provides some advice on the following troubleshooting steps:

  • Enabling logging in REST calls - this can be achieved by disabling the suppression of internal operations. Rest calls via the HTTP connection handler generate internal operations against DS, which can help you understand exactly what the interface is trying to do as opposed to what you've configured it to do. It is recommended that you do not use your DS server for anything else while you are logging internal operations to avoid noise in the logs.

You can also enable logging in the REST to LDAP (REST2LDAP) gateway servlet if it runs in the Apache Tomcat™ web container. Logging will also help identify any access control issues (see next step).

  • Checking access controls (ACI) - this can be achieved by performing the same operation with the same credentials using an LDAP client. If you cannot perform the operation, then you will need to adjust the ACI in DS to allow these operations. The DS logs will also identify any access control issues.
  • Checking the format of your REST calls - you should ensure you have formed your REST call correctly according to which mechanism you are using for REST as the expected format differs.

Enabling logging in REST calls

The REST interface included in DS's HTTP connection handler uses an internal connection inside DS to translate the REST query into a series of LDAP operations. These are not logged by default. Logging these operations can be extremely beneficial when you are developing your REST configuration. However, this will result in a lot of extra access logging, so it is only recommended in your development environment.


You can only log internal operations for the HTTP connection handler; although the external REST2LDAP gateway servlet uses normal LDAP connections to communicate with DS, these operations are not included when logging is enabled since the servlet is an external application running within the web container. DS may use internal operations during normal activities so changing this setting may result in a lot of additional logging.

To log these internal operations when using the HTTP connection handler, use the dsconfig command appropriate to your version:

  • DS 7.1  and later: $ ./dsconfig set-log-publisher-prop --hostname --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "Json File-Based Access Logger" --set suppress-internal-operations:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/ --no-prompt
  • DS 7: $ ./dsconfig set-log-publisher-prop --hostname --port 4444 --bindDN uid=admin --bindPassword password --publisher-name "Json File-Based Access Logger" --set suppress-internal-operations:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/ --no-prompt
  • Pre-DS 7: $ ./dsconfig set-log-publisher-prop --hostname --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "Json File-Based Access Logger" --set suppress-internal-operations:false --trustAll --no-prompt

Here is an example of the logging produced by a REST call to create a new user:

{"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"CONNECT","connId":29},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS"},"timestamp":"2020-02-10T16:21:01.435Z","_id":"ad44b318-3d53-4886-a63d-0d405d28eb40-14"} {"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"SEARCH","connId":29,"msgId":2,"dn":"ou=people,dc=example,dc=com","scope":"wholeSubtree","filter":"(&(objectClass=inetOrgPerson)(uid=user.0))","attrs":["1.1"]},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":2,"elapsedTimeUnits":"MILLISECONDS","nentries":1},"timestamp":"2020-02-10T16:21:01.621Z","_id":"ad44b318-3d53-4886-a63d-0d405d28eb40-15"} {"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"BIND","connId":29,"msgId":1,"version":"3","dn":"uid=user.0,ou=People,dc=example,dc=com","authType":"SIMPLE"},"transactionId":"ad44b318-3d53-4886-a63d-0d405d28eb40-18","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":11,"elapsedTimeUnits":"MILLISECONDS"},"userId":"uid=user.0,ou=People,dc=example,dc=com","timestamp":"2020-02-10T16:21:01.658Z","_id":"ad44b318-3d53-4886-a63d-0d405d28eb40-18"} {"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"ADD","connId":29,"msgId":1,"dn":",ou=People,dc=example,dc=com"},"transactionId":"ad44b318-3d53-4886-a63d-0d405d28eb40-20" {"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"UNBIND","connId":29,"msgId":3},"transactionId":"ad44b318-3d53-4886-a63d-0d405d28eb40-22","timestamp":"2020-02-10T16:21:01.699Z","_id":"ad44b318-3d53-4886-a63d-0d405d28eb40-24"} {"eventName":"DJ-LDAP","client":{"ip":"","port":8443},"server":{"ip":"","port":1636},"request":{"protocol":"LDAPS","operation":"DISCONNECT","connId":29},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS","reason":"Client Unbind"},"timestamp":"2020-02-10T16:21:01.699Z","_id":"ad44b318-3d53-4886-a63d-0d405d28eb40-26"}​​​​​​​

You can enable logging in the REST to LDAP (REST2LDAP) gateway servlet if it runs in the Apache Tomcat™ web container. This is done by specifying logging properties in the file (located in the WEB-INF/classes directory where the gateway servlet is deployed).

Checking access controls (ACI)

All REST requests result in a number of LDAP operations. As a consequence, any REST operation performed is subject to exactly the same access controls (ACI) configured in DS as normal LDAP operations.

If you are having trouble reading or writing resources, it is recommended that you try to repeat the same operation (using the same credentials) using DS's ldapmodify or ldapsearch tools. When they work as expected, you should get similar results from the REST interface.

See Client Problems for further information on using the logs to identify and resolve access control issues.


It is good practice to put the ACI in the actual backend, as this means it will be replicated and also included when you export the data. Global ACIs are not replicated and are easy to forget when you're creating new instances.

Checking the format of your REST calls

When making a REST call, you must authenticate as a user (in this example, username = jdoe and password = changeit). You can authenticate in two different ways, regardless of the REST mechanism you are using:

  • By using curl's --user flag, for example using the HTTP connection handler: $ curl --user jdoe:changeit
  • By embedding the credentials in the URL, for example using the REST2LDAP gateway servlet: $ curl

See Also

Troubleshooting DS

HTTP Access

Install a REST to LDAP Gateway

REST to LDAP Reference

Access Control

Related Training


Related Issue Tracker IDs

OPENDJ-2403 (DSML servlet does not log errors for LDAP operations)

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.