FAQ

FAQ: REST API in DS/OpenDJ

Last updated Jul 9, 2018

The purpose of this FAQ is to provide answers to commonly asked questions regarding the REST API in DS/OpenDJ.


Frequently asked questions

Q. Can I use cn=Directory Manager for creating new entries?

A. You cannot easily do this if you use the HTTP connection handler nor is it recommended. If you use the REST2LDAP gateway servlet, you can achieve this as follows depending on which version of DS/OpenDJ you use:

  • DS / OpenDJ 3.5: set the bind to simple under authorization > basic to allow you to pick specific bind DNs.
  • Pre-OpenDJ 3.5: set the method to simple in the authenticationFilter to allow you to pick specific bind DNs.

However, best practice is to create a separate administrative user under the base DN who has the necessary access controls (ACIs) for creating the required entries. See Security Guide › Managing Administrator Accounts for further information.

Q. Can I do a negation query with the REST API?

A. Yes, you can using the boolean operator ! (not). Examples of queries that can be performed via REST (with the equivalent LDAP filter for comparison) are shown in Developer's Guide › Querying Resource Collections.

Q. Can I trace what is happening when a REST call is made for troubleshooting purposes?

A. Yes, if you are using the HTTP connection handler, you can enable logging for the REST interface as described in How do I troubleshoot a DS/OpenDJ (All versions) REST configuration?

As of OpenDJ 3.5, you can also enable logging in the REST to LDAP (REST2LDAP) gateway servlet if it runs in the Apache Tomcat™ web container. This is also described in How do I troubleshoot a DS/OpenDJ (All versions) REST configuration?

Q. Can I create password policies at the system level using the REST API?

A. Yes you can add and edit password policy definitions at the system level using REST (over the /admin/config endpoint) in OpenDJ 3.5 and later provided you have created the necessary mapping details in the Mapping Configuration file. See Developer's Guide › Adding Subentry Password Policies for an example.

Note

It is not possible to assign a password policy to specific users or groups using REST, nor to see and manage a user's password state (that is, locked, reset, etc.).

In pre-OpenDJ 3.5 versions, the REST API is suited to endpoints with immediate subordinate entries, which works well for users and groups, but is less well suited for reading entries from arbitrary points in the DIT. If all your password policies are at the same level in the DIT, then you can create another endpoint in your REST configuration (http-config.json file). See  OpenDJ Reference › REST to LDAP Configuration (3.0) for further information.

Q. Are there any REST endpoints in DS/OpenDJ for creating organizational units and organizations?

A. Endpoints in the DS/OpenDJ REST API can be configured to allow the creation of any type of entry in the DS/OpenDJ DIT.

As of OpenDJ 3.5, it is possible to define relationships between resources using SubResources, meaning entries can be created at different levels beneath the base DN. You can configure mapping details for a resource in the mapping configuration file to allow organizational units and organizations to be created; these resource details should be similar to the existing users resource, which allows you to create person objects below ou=People,dc=example,dc=com. See Reference › REST to LDAP Configuration for further information and specifically Reference › REST to LDAP Configuration › Mapping Configuration File for details about the mapping configuration file.

In pre-OpenDJ 3.5, each endpoint was restricted to only allowing new entries directly beneath the base DN in the endpoint configuration. You can configure endpoints and the corresponding base DN in the http-config.json file to allow organizational units and organizations to be created; these endpoints should be similar to the existing /users endpoint, which allows you to create person objects below ou=People,dc=example,dc=com. See OpenDJ Reference › REST to LDAP Configuration (3.0) for further information.

Resolved RFE: OPENDJ-2871 (Add support for sub-resources).

Q. Can I define mappings/resources using search scopes and filters in the same way as for LDAP searches?

A. No, the way mappings/resources are defined in the REST API is not directly equivalent to LDAP searches. The concept of a subtree scope for searches does not relate to mappings as the server needs to be able to compute base DNs based on the REST resources. The concept of a subtree search does not fit this model. For example, if a CREATE operation was issued, the server would not know where to write the new entry in the tree. Each mapping needs to be definable in a way that you can map the REST resource to base DN and vice versa in a strictly defined way; this is done using namingStrategy in the REST API. 

See the following for further information on namingStrategy, depending on which version of DS/OpenDJ you are using:

You cannot use filters for defining the collections included in the mappings. However, you can run filters when using the REST interface by including them in a QUERY.

Q. Does the REST API support user names and identifiers that contain *?

A. Yes, the REST API in DS/OpenDJ does work with user names and identifiers containing *. However, there is a serious risk that LDAP client applications may not escape the * character when using it in String representation of LDAP search filters, which will result in heavy, resource consuming requests in the directory.

Note

It is recommended that you avoid using * (and other special characters) in your user names and identifiers to avoid any potential issues.

Q. How can I retrieve data for a user who is under a different base DN (pre-OpenDJ 3.5)?

A. You must add another mapping to the http-config.json file to achieve this. The following mapping exists by default:

{
        "mappings" : {
            "/users" : {
                "baseDN"              : "ou=people,dc=example,dc=com",
}

If you want to query users under another base DN, for example: ou=employees,ou=people,dc=example,dc=com, you would need to add a second mapping and restart the server:

{
            "/otherusers" : {
                "baseDN"              : "ou=employees,ou=people,dc=example,dc=com",
}

A RFE exists for making this dynamic: OPENDJ-2888 (Implement a dynamic routing and mapping mode for Rest2LDAP).

See Also

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

Administration Guide › RESTful Client Access

Developer's Guide › Performing RESTful Operations

Administration Guide › Configuring Privileges and Access Control › About ACIs

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-2888 (Implement a dynamic routing and mapping mode for Rest2LDAP)

OPENDJ-2871 (Add support for sub-resources)

OPENDJ-2196 (OpenDJ does not return the isMemberOf attribute via REST)



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...