Managing the Directory REST API
The Directory REST API is the native interface for client access to the PingDirectory server.
About this task
Instead of trying to manage directory hierarchy or require attribute mapping, the Directory REST API provides direct access to directory data in a way that is dynamic, discoverable, and efficient. For more information, see PingDirectory REST API Reference and the Developer portal.
The Directory REST API gives developers who are more comfortable with REST than LDAP access to arbitrary directory data in a way that ensures that directory data remains consistent regardless of whether it is accessed from LDAP or REST.
The Directory API is enabled during server setup. After setup, individual services and applications can be enabled or disabled by configuring the HTTPS Connection Handler.
Although both the Directory REST API and System for Cross-domain Identity Management (SCIM) provide REST access to directory data, the goals of the two protocols are different. SCIM is useful to generic, external clients that require simple, narrow access to identity data, but because it’s a less common standard for identity stores, it might not offer as much functionality or be as user-friendly as the Directory REST API.
The Directory REST API can be used for the following operations.
HTTP operation | Resource endpoint | Description | Allowed query parameters | ||
---|---|---|---|---|---|
DELETE |
|
Delete an entry |
Not applicable |
||
GET |
|
Get metadata about the API and server |
Not applicable |
||
GET |
|
Retrieve a single entry |
|
||
GET |
|
Search an entry’s descendants |
|
||
GET |
|
Retrieve the schemas of all available object classes |
Not applicable |
||
GET |
|
Retrieve schema for a specific object class |
Not applicable |
||
GET |
|
Retrieve schema for operational attributes |
Not applicable |
||
GET |
|
Alias for retrieving the current user |
Not applicable |
||
PATCH |
|
Modify an entry (add or delete values) |
|
||
POST |
|
Create a new entry |
|
||
POST |
|
Generate a new password suggestion |
Not applicable |
||
POST |
|
Get password quality requirements |
Not applicable |
||
POST |
|
Modify an existing password |
Not applicable |
||
POST |
|
Generate an access token using a password only, or a password in combination with a TOTP, OTP, or registered YubiKey |
Not applicable |
||
POST |
|
Generate a time-based, one-time shared secret to exchange for a TOTP |
Not applicable |
||
POST |
|
Revoke a time-based, one-time shared secret |
Not applicable |
||
POST |
|
Generate an OTP and deliver it to the user out of band |
Not applicable |
||
POST |
|
Register a YubiKey device for a particular user |
Not applicable |
||
POST |
|
Revoke a YubiKey device for a particular user |
Not applicable |
||
PUT |
|
Modify or rename an entry |
|
Steps
-
Configure the Directory REST API with any of the following properties using
dsconfig
:Command Description basic-auth-enabled
Specifies whether users can connect to the service with HTTP basic authentication. If disabled, users need a bearer token. If changed, the server must be restarted, or any HTTP Connection Handlers referencing this service disabled and re-enabled.
Basic authentication is enabled by default.
identity-mapper
If HTTP basic authentication is enabled, the identity mapper referenced by this distinguished name (DN) must be used to map the user names provided to user entries. By default, an identity mapper is provided, which maps a fully-qualified DN to an entry.
For changes to take effect, the server must be restarted, or any HTTP connection handlers referencing this service disabled and re-enabled.
access-token-validator
Specifies the subset of this server’s access token validators (by DN), which can validate bearer authentication tokens. By default, if no validators are specified, then any of the validators on the server can be used.
For changes to take effect, the server must be restarted, or any HTTP connection handlers referencing this service disabled and re-enabled.
access-token-scope
The scope that must be present in bearer tokens in order to be accepted by this service. If no value is provided, bearer token authentication is disabled, and only basic authentication is used.
By default, no value is provided. Changes to this value take effect immediately.
audience
A string or URI audience that must be present in Bearer tokens in order to be accepted by this service. If no value is provided, any audience is acceptable.
By default, no value is provided. Changes to this value take effect immediately.
max-page-size
The maximum number of entries to be returned in one page from the search endpoint. Actual results returned might be lower because of the limit query parameter on the request and the actual number of available results.
The value must be an integer between 1 and 1000. The default value is 100. Changes to this value take effect immediately.
schemas-endpoint-objectclass
The list of object classes that will be returned by the
/directory/v1/schemas
to retrieve the schemas of all available object classes in the REST API.By default, no schemas are returned. Changes to this value take effect immediately.
Example:
The following example uses
dsconfig
to configure anobjectClass
entity:dsconfig set-http-servlet-extension-props --extension-name "Directory REST API" \ --add schemas-endpoint-objectclass:ubidPerson