FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: REST API in DS

Last updated Apr 8, 2021

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


Frequently asked questions

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 REST API Guide › Query

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 and the REST to LDAP (REST2LDAP) gateway servlet if it runs in the Apache Tomcat™ web container. See How do I troubleshoot a DS (All versions) REST configuration? for further information.

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) provided you have created the necessary mapping details in the API Configuration. See HTTP User Guide › 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.).

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

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

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 HTTP User Guide › REST to LDAP Reference for further information.

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 HTTP User Guide › REST to LDAP Reference for further information on namingStrategy.

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 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. Can I use cn=Directory Manager for creating new entries (pre-DS 7)?

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 by setting the bind to simple under authorization > basic 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.

See Also

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

Configuration Guide › HTTP Access

HTTP User Guide › DS REST APIs

Security Guide › Access Control

Related Training

N/A

Related Issue Tracker IDs

N/A



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