PingDirectory

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. Learn more in the 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.

You can define ACIs in PingDirectory that map to specific OAuth scopes. When users make requests to Directory REST API endpoints using OAuth 2.0 bearer tokens that include configured scopes, PingDirectory can apply the ACIs associated with those scopes and grant the appropriate permissions. Learn more in Using OAuth scopes for ACI rules with the REST API.

Invoking ACIs using OAuth scopes applies to all REST API endpoint requests except for the following:

  • GET /directory/v1/

  • GET /directory/v1/schemas

  • GET /directory/v1/schemas/{schema}

The Directory REST API can be used for the following operations.

HTTP operation Resource endpoint Description Allowed query parameters

DELETE

/directory/v1/{{dn}}

Delete an entry

Not applicable

GET

/directory/v1

Get metadata about the API and server

Not applicable

GET

/directory/v1/{{dn}}

Retrieve a single entry

  • expand

  • includeAttributes

  • excludeAttributes

GET

/directory/v1/{{dn}}/subtree

Search an entry’s descendants

  • filter

  • searchScope

  • cursor

  • limit

  • includeAttributes

  • excludeAttributes

GET

/directory/v1/schemas

Retrieve the schemas of all available object classes

Not applicable

GET

/directory/v1/schemas/{objectclass}

Retrieve schema for a specific object class

Not applicable

GET

/directory/v1/schemas/_operationalAttributes

Retrieve schema for operational attributes

Not applicable

GET

/directory/v1/me

Alias for retrieving the current user

Not applicable

PATCH

/directory/v1/{{dn}}

Modify an entry (add or delete values)

expand

POST

/directory/v1

Create a new entry

expand

POST

/directory/v1/suggestPassword

Generate a new password suggestion

Not applicable

POST

/directory/v1/passwordRequirements

Get password quality requirements

Not applicable

POST

/directory/v1/{{dn}}/changePassword

Modify an existing password

Not applicable

POST

/directory/v1/authenticate

Generate an access token using a password only, or a password in combination with a TOTP, OTP, or registered YubiKey

Not applicable

POST

/directory/v1/{{dn}}/generateTOTPSharedSecret

Generate a time-based, one-time shared secret to exchange for a TOTP

Not applicable

POST

/directory/v1/{{dn}}/revokeTOTPSharedSecret

Revoke a time-based, one-time shared secret

Not applicable

POST

/directory/v1/deliverOneTimePassword

Generate an OTP and deliver it to the user out of band

Not applicable

POST

/directory/v1/{{dn}}/registerYubiKeyOTPDevice

Register a YubiKey device for a particular user

Not applicable

POST

/directory/v1/{{dn}}/deregisterYubiKeyOTPDevice

Revoke a YubiKey device for a particular user

Not applicable

PUT

/directory/v1/{{dn}}

Modify or rename an entry

expand

You can’t update a user’s userPassword or authPassword attributes with this operation.

Instead, use the /directory/v1/{{dn}}/changePassword endpoint to update passwords.

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. To disable basic authentication, enter the following command:

    dsconfig set-http-servlet-extension-props \
    --extension-name "Directory REST API" \
    --set basic-auth-enabled:false

    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 an objectClass entity:

    dsconfig set-http-servlet-extension-props \
    --extension-name "Directory REST API" \
    --add schemas-endpoint-objectclass:ubidPerson