The following changes have been made to the PingDirectory REST API.

Requesters can authenticate using any of two authentication types, and the requester may have either a privileged or unprivileged identity that determines the activity scope.

Authentication types

The Directory REST API supports the following authentication types:

• Basic authentication

  Requests are authenticated using a username and password or an encoded API token contained in the Authorization header. The user credentials can be collected interactively from the user, or they can represent the client itself.

  Here is a sample of a request using an API token:

  GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
  
  Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9wbGUsZGM9ZXhhbXBsZSxkYz1jb206cGFzc3dvcmQ=
  

• Bearer token

  Requests are authenticated using an access token contained in the Authorization header. The access token is obtained through an authorization server, such as PingFederate. Here is a sample:

  GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
  Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp...
  

  When bearer token authentication is used, the access token used must include a scope that the directory service is configured to accept. Additionally, the directory service may be configured to require that the access token include a specific audience claim.

  You can define ACIs in PingDirectory that map to specific 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.

Access control

To help isolate access to admin credentials in authentication workflows, you can use OAuth scopes to enforce access control instructions (ACIs) for users authenticating to specific Directory REST API endpoints.

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

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

Making requests to the Directory REST API with a given user is similar to making an LDAP request with the same user and is subject to the same ACI restrictions. Authenticated users can have full or partial access to the Directory service based on the permissions allowed for that user. In other words, scopes are granted dynamically, and are not explicitly stated in the bearer token. The client sending the bearer token in their request is granted permissions by the access token validator at the time of the request.

To enable this feature, define the ACIs to include the desired OAuth scopes. The following example allows all authenticated users with the OAuth scope example:scope to perform the Get Password Quality Requirements extended operation:

(extop="1.3.6.1.4.1.30221.2.6.43")(version 3.0; acl "Extended op permissions for get password quality requirements"; allow (read) oauthscope="example:scope";)

Learn more in Managing the Directory REST API and Using OAuth scopes for ACI rules with the REST API in the PingDirectory admin guide.

Create the request

The following information illustrates how to construct a typical API request.

Request header

The API request header contains the authentication information you must provide to make a call to any Directory REST API resource. The Authorization parameter takes the user credentials or the full bearer token as its value, which contains the authorization information needed to access the requested resource.

The following sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded bearer token as its parameter value.

curl -X "GET" "https://<server>/directory/v1/{dn}" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

The request header also shows an additional parameter or note:

• Content-Type

  In the header of a PATCH, PUT, or POST request, this parameter identifies the media type of the request data sent to the server. For most Directory API calls, the Content-Type is application/json.

Request body

The API request body for POST, PATCH, or PUT requests provides the attribute values needed to complete the create or update operation. For example, to update an LDAP entry, the PUT operation requires values for the attr1 and attr2 attributes in the request body:

{
  "attr1": "value1",
  "attr2": "value2"
}

The Directory REST API includes endpoints perform create, read, update, and delete operations on PingDirectory Server entries. Entries are identified in the request URL by their distinguished name {dn}.

Endpoint Examples

In the following examples, an attribute is represented as a name-value pair within the entry JSON object. Attribute values are given as either a single JSON value, or as an array of JSON values, according to whether the attribute is single-valued or multi-valued in the schema.

Individual values can be one of four types: string, integer, boolean, or JSON object. Floating point numbers should be provided as strings since LDAP does not support floating point numbers. Dates are provided in the ISO-8601 format, and binary values are represented as Base64-encoded strings.

Example:

"createTimestamp": "2018-05-01T15:04:49.866Z""ubidEmailJSON": [
  {
    "type": "work",
    "value": "ljones@example.com"
  }
]

Attribute names are always case sensitive and must be specified in the exact form as they appear in the schema. These rules apply for both request and response entities.

The Directory REST API includes operations to list the schemas of all available objectClass objects and view schema details for specified objectClass entities.

The Directory REST API includes operations to retrieve a list of entries under a subtree of an entry, and to search the subtree using a POST request to avoid placing confidential information in the request URI.

The PingDirectory REST API supports a top-level authenticate endpoint used to authenticate users.

In most cases, requests sent to the authenticate endpoint will not require and should not include an Authorization header. The only exception to this would be if the request is attempting to use a control that is only available to authorized users. If the request does include an Authorization header, then it must be validated and used to identify the associated user.

Supported credential types

In an authenticate request, the credentials element must be a JSON object with a set of credentials for the desired type of authentication. All types of authentication must include an authenticationType field in the credentials object that specifies what type of authentication to use. The following authenticationType values are supported:

• password

  The password authentication type identifies a user with either a username or a DN and only uses a static password as the credentials. The following additional fields are allowed in the credentials object:

  • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • staticPassword — A mandatory string field whose value is the static password for the target user.

• passwordPlusTOTP

  The passwordPlusTOTP authentication type identifies a user with either a username or a DN and uses both a static password and a time-based one-time password (TOTP) as the credentials. For TOTP shared secret management, see Generate TOTP shared secret and Revoke TOTP shared secret. The following additional fields are allowed in the credentials object:

  • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • staticPassword — A mandatory string field whose value is the static password for the target user.

  • totp — A mandatory string field whose value is the time-based one-time password for the target user.

• passwordPlusDeliveredOTP

  The passwordPlusDeliveredOTP authentication type identifies a user with either a username or a DN and uses both a static password and a one-time password that has been delivered to the user through a method like email or SMS. The one-time password will be valid for a limited period of time, and it will only be valid for a single authentication attempt. This authentication type uses the deliver one-time password extended operation.

  Once the deliver one-time password extended request has been used and the one-time password has been generated and delivered to the user, the authenticate endpoint can be used to authenticate with that one-time password. The following additional fields are allowed in the credentials object:

  • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • otp — A mandatory string field whose value is the one-time password that was delivered to the target user.

• passwordPlusYubiKeyOTP

  The passwordPlusYubiKeyOTP authentication type identifies a user with either a username or a DN and uses both a static password and one-time password generated by a YubiKey device as the credentials. For information on YubiKey device management, see Register YubiKey OTP device and Deregister YubiKey OTP device. The following additional fields are allowed in the credentials object:

  • dn — An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • username — An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

  • staticPassword — A mandatory string field whose value is the static password for the target user.

  • otp — A mandatory string field whose value is the one-time password generated by the YubiKey device.

The requests for creating, updating, deleting, and searching entries support the _controls property, which is a JSON field added to the requests and responses. The property specifies an array of JSON formatted controls that provide additional content in LDAP requests and responses.

LDAP controls consist of these attributes:

• oid: A required object identifier (OID) that identifies the type of control. Each type of control must have its own unique OID, although request and response controls of the same type may optionally share the same OID. When the server receives an LDAP request with one or more controls, it uses the OID to determine the kind of control it is so that it can determine how to process it. Similarly, clients can identify the type of a response control based on its OID.

• control-name: An optional string field that specifies the user-friendly name of the control.

• criticality: A required Boolean that indicates whether the control should be considered a critical part of the operation. If a request control is critical, and if the server does not support it for the requested operation, or if the client does not have permission to request it, then the server must reject the operation with an unavailableCriticalExtension result. Conversely, if a non-critical request control cannot be honored, then the server simply ignores it. Response controls should always have a criticality of false.

• value-base64: An optional string field whose value is the base64-encoded representation of the raw value for the control when encoded in LDAP. Note that this should only consist of the value of the controlValue element of the control sequence, rather than an encoded representation of the entire octet string element.

• value-json: An optional property that provides additional information for use with the control. The format for the value varies from one type of control to another. Some types of controls do not require a value because the mere presence of a control with a given OID is sufficient to achieve the desired purpose (for example, the manage DSA IT request control may be used to indicate that the server should treat smart referral entries as regular entries, and no additional information is needed by that control).

For examples of the _controls property in requests, see Create Entry with Controls and Search Using POST with Controls.

The standard assertion request control may be included in an add, compare, delete, modify, modify DN, or search request to indicate that the operation should only be processed if the target entry matches a given filter. The control has an OID of 1.3.6.1.1.12, and it takes a value. The following fields may be present in the value-json representation of the value:

• filter: A required string field whose value is the string representation of the filter that the target entry must match.

The following sample shows the JSON encoding for the control:

{ "oid":"1.3.6.1.1.12",
  "control-name":"Assertion Request Control",
  "criticality":true,
  "value-json":{ "filter":"(objectClass=person)" 
  } 
}

This control may be included in an add, delete, modify, or modify DN request to indicate that the server should delay the response for that operation until it has satisfied certain replication requirements. The control has an OID of 1.3.6.1.4.1.30221.2.5.28, and it takes a value. The following fields may be present in the value-json representation of the value:

• minimum-local-level: An optional string field whose value is the name of the minimum assurance level desired for replicas in the same location as the target server. The value may be one of "none", "received-any-server", or "processed-all-servers". If this is not specified, then the server will choose an appropriate minimum local assurance level based on its configuration.

• maximum-local-level: An optional string field whose value is the name of the maximum assurance level desired for local replicas. If specified (with a value of "none", "received-any-server", or "processed-all-servers"), it may cause the server to use a lower local assurance level than it may have otherwise chosen based on configuration. If this is not specified, then the server will choose an appropriate maximum local assurance level based on its configuration and the minimum local assurance level.

• minimum-remote-level: An optional string field whose value is the name of the minimum assurance level desired for replicas in a different location from the target server. The value may be one of "none", "received-any-remote-location", "received-all-remote-locations", or "processed-all-remote-servers". If this is not specified, then the server will choose an appropriate minimum remote assurance level based on its configuration.

• maximum-remote-level: An optional string field whose value is the name of the maximum assurance level desired for remote replicas. If specified (with a value of "none", "received-any-remote-location", "received-all-remote-locations", or "processed-all-remote-servers"), it may cause the server to use a lower remote assurance level than it may have otherwise chosen based on configuration. If this is not specified, then the server will choose an appropriate maximum remote assurance level based on its configuration and the minimum remote assurance level.

• timeout-millis: An optional integer field whose value specifies the maximum length of time in milliseconds that the server should wait for assurance to be satisfied. If this is not specified, then the server will choose an appropriate timeout.

• send-response-immediately: A Boolean field that indicates whether the server should return the response to the client immediately after applying the change locally, even if it has not yet been replicated. Sending the response immediately is primarily useful if the client will monitor the replication status for the operation.

The following sample shows the JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.28",
  "control-name":"Assured Replication Request Control",
  "criticality":false,
  "value-json":{ "minimum-local-level":"received-any-server",
                 "minimum-remote-level":"received-any-remote-location",
                 "timeout-millis":1000
    } 
}

This control may be used to convey the results of processing for an assured replication request control. The control has an OID of 1.3.6.1.4.1.30221.2.5.29, and it takes a value. The following fields may be present in the value-json representation of the value:

• local-level: An optional string field that specifies the local assurance level used for the operation. If present, its value will be one of "none", "received-any-server", or "processed-all-servers".

• local-assurance-satisfied: A Boolean field that indicates whether the local assurance requirement was satisfied for the operation.

• local-assurance-message: An optional string field that provides additional information about the local assurance processing for the operation.

• remote-level: An optional string field that specifies the remote assurance level used for the operation. If present, its value will be one of "none", "received-any-remote-location", "received-all-remote-locations", or "processed-all-remote-servers".

• remote-assurance-satisfied: A Boolean field that indicates whether the remote assurance requirement was satisfied for the operation.

• remote-assurance-message: An optional string field that provides additional information about the remote assurance processing for the operation.

• csn: An optional string field that provides the change sequence number (CSN) that the server assigned for the operation.

• server-results: An optional array of JSON objects that provides individual results from the local and/or remote servers used in replication assurance processing. These JSON objects may include the following fields:

  • result-code-value: An integer field that specifies the numeric value for the result code for server assurance processing.

  • result-code-name: An optional string field whose value is the name of the result code for server assurance processing.

  • replication-server-id: An optional integer field that specifies the server ID for the associated replication server.

  • replica-id: An optional integer field that specifies the replica ID for the associated replica.

At present, the defined set of result codes that may be used in assured replication server results are:

• complete (0): Indicates that the replicated operation completed successfully.

• timeout (1): Indicates that the replicated operation did not complete within the associated timeout period.

• conflict (2): Indicates that assurance was not satisfied because a conflict was detected.

• server-shutdown (3): Indicates that assurance was not satisfied because the server was shutting down.

• unavailable (4): Indicates that assurance was not satisfied because the server was not available.

• duplicate (5): Indicates that the server determined that the operation was a duplicate of another operation.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.29",
  "control-name":"Assured Replication Response Control",
  "criticality":false,
  "value-json":{ "local-level":"received-any-server",
                 "local-assurance-satisfied":true,
                 "remote-level":"received-any-remote-location",
                 "remote-assurance-satisfied":true,
                 "csn":"1234567890ABCDEF1234567890AB",
                 "server-results":[ { "result-code-value":0,
                                      "result-code-name":"complete",
                                      "replication-server-id":1234 },
                                    { "result-code-value":0,
                                      "result-code-name":"complete",
                                      "replication-server-id":5678 } 
                                     ] 
                    } 
    }

The proprietary exclude branch request control may be included in a search request to indicate that the server should exclude matching entries in one or more subtrees. The control has an OID of 1.3.6.1.4.1.30221.2.5.17, and it takes a value. The following fields may be present in the value-json representation of the value:

• base-dns: A mandatory array field whose values must be strings that represent the base DNs of the branches to exclude from search results.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.17",
  "control-name":"Exclude Branch Request Control",
  "criticality":false,
  "value-json":{ 
      "base-dns":[ "ou=excluded 1,dc=example,dc=com",
                              "ou=excluded 2,dc=example,dc=com"
        ] 
    } 
}

The proprietary generate password request control may be included in an add request to indicate that the server should generate a new password for the entry. The control has an OID of 1.3.6.1.4.1.30221.2.5.58, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.58",
    "control-name":"Generate Password Request Control",
    "criticality":false
}

This control may be included in the response to an add request that included the generate password request control, and it provides information about the password that was generated. The control has an OID of 1.3.6.1.4.1.30221.2.5.59, and it takes a value. The following fields may be present in the value-json representation of the value:

• generated-password: A string field that holds the password that was generated for the entry.

• must-change-password: A Boolean field that indicates whether the user must choose a new password before they will be allowed to request any other operations.

• seconds-until-expiration: An optional integer field that indicates the number of seconds until the new password expires.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.59",
  "control-name":"Generate Password Response Control",
  "criticality":false,
  "value-json":{ "generated-password":"CorrectHorseBatteryStaple",
                 "must-change-password":true,
                 "seconds-until-expiration":86400 } }

The proprietary get effective rights request control may be included in a search request to indicate that matching entries should include one or more aclRights attributes with the access control permissions that a given user may have when interacting with the entry. The control has an OID of 1.3.6.1.4.1.42.2.27.9.5.2, and it takes a value. The following fields may be present in the value-json representation of the value:

• authorization-id: A mandatory string field whose value is the authorization identity of the user for whom to make the access control determination.

• attributes: An optional array field whose values are the names of the attributes for which to calculate effective rights. If this is not provided, or if it is empty, then the default behavior calculates effective rights for all user attributes in the entry.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.42.2.27.9.5.2",
    "control-name":"Get Effective Rights Request Control",
    "criticality":false,
    "value-json":{ 
        "authorization-id":"dn:uid=jdoe,ou=People,dc=example,dc=com",
        "attributes":[ 
            "uid",
            "mail",
            "telephoneNumber",
            "userPassword" 
            ] 
    } 
}

This control can be included in a delete request to override any soft delete policies and remove the target entry from the server completely. Learn more about soft delete policies in Soft delete request control.

The following example shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.22",   
    "control-name":"Hard Delete Request Control",
    "criticality":true,
}

The proprietary ignore NO-USER-MODIFICATION request control may be included in an add request to indicate that the server should allow the client to set all of the provided attributes, even if some of the attribute types are defined with the NO-USER-MODIFICATION constraint in the schema. The control has an OID of 1.3.6.1.4.1.30221.2.5.5, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    oid":"1.3.6.1.4.1.30221.2.5.5",
    "control-name":"Ignore NO-USER-MODIFICATION Request Control",
    "criticality":false 
}

The proprietary intermediate client request control may be included in any type of request, and may serve a few different purposes:

• It may indicate that the request originated from a downstream client, in which case the control may provide additional information about interaction with that client and any other intermediate systems.

• It indicates that the server should provide information about its processing of the operation (along with information from any other upstream servers) that can be used to correlate information about the processing of the operation across multiple systems.

• It can be used to request that the operation be processed with an alternative authorization identity. In this respect, it is similar to the proxied authorization v1 or v2 request control, except the intermediate client control allows multiple authorization requests to be nested.

The intermediate client request control has an OID of 1.3.6.1.4.1.30221.2.5.2, and it takes a value. The following fields may be present in the value-json representation of the value:

• downstream-request: An optional JSON object field whose value is the representation of information from a downstream client. If present, the fields that may be included in this JSON object are the same fields that may be included in the value-json object of the intermediate client request control (optionally including yet another nested downstream-request field).

• downstream-client-address: An optional string field whose value is the address of the immediate client from which the request was received. For example, the Directory Proxy Server uses this field to pass the address of the end LDAP client to the backend Directory Server used to process the request.

• downstream-client-secure: An optional Boolean field whose value indicates whether communication with the immediate downstream client is using a secure channel. For example, the Directory Proxy Server uses this field to indicate to the backend Directory Server whether the communication between the end LDAP client and the Directory Proxy Server is secure.

• client-identity: An optional string field whose value contains the authorization identity of a user under whose authority the operation should be processed. For example, the Directory Proxy Server uses this field to indicate that the operation should be processed using the authorization identity of the end LDAP client rather than as the account the Directory Proxy Server uses to authenticate itself to the backend Directory Server.

• client-name: An optional string field whose value contains the name of the application that generated this control. For example, the Directory Proxy Server uses this field to indicate that the request has passed through the Directory Proxy Server.

• client-session-id: An optional string field whose value contains an identifier that this client is using to reference the current communication session with a downstream client. For example, the Directory Proxy Server uses this field to hold the connection ID that it has assigned to the connection it is using to communicate with the end LDAP client.

• client-request-id: An optional string field whose value contains an identifier that this client is using to reference the current request from a downstream client. For example, the Directory Proxy Server uses this field to hold the operation ID it has assigned to the operation being forwarded to the backend Directory Server.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.2",
    "control-name":"Intermediate Client Request Control",
    "criticality":false,
    "value-json": { 
        "downstream-client-address":"1.2.3.4",
        "downstream-client-secure":true,
        "client-identity":"dn:uid=jdoe,ou=People,dc=example,dc=com",
        "client-name":"PingDirectoryProxy",
        "client-session-id":"conn=1234",
        "client-request-id":"op=56" 
    } 
}

This control may be included the response to a request that contains an intermediate client request control, and it may be used to provide information about the processing performed by the current server and any upstream servers. The control has an OID of 1.3.6.1.4.1.30221.2.5.2, and it takes a value. The following fields may be present in the value-json representation of the value:

• upstream-response: An optional JSON object field whose value provides information about processing performed by a server that is upstream from the one with which the client is communicating. If present, the fields of this JSON object are the same as the fields of the value-json object (potentially including another nested upstream-response object).

• upstream-server-address: An optional string field whose value is the address of an upstream server to which the requested operation was forwarded. For example, if the Directory Proxy Server receives a request that contains an intermediate client request control, it will use this field in the intermediate client response control it returns to provide the address of the backend Directory Server to which the operation was forwarded.

• upstream-server-secure: An optional Boolean field used to indicate whether communication with an upstream server occurred over a secure communication channel. For example, if the Directory Proxy Server receives a request that contains an intermediate client request control, it will use this field in the intermediate client response control it returns to indicate whether its communication with the backend Directory Server is secure.

• server-name: An optional string field whose value is the name of the application used to process the request. For example, the Directory Server uses this field to indicate that the operation was processed by the Directory Server.

• server-session-id: An optional string field whose value is an identifier that the server has assigned to the communication session with the downstream client. For example, the Directory Server uses this field to specify the connection ID it has assigned to the client connection.

• server-response-id: An optional string whose value is an identifier that the server has assigned to the request from the downstream client. For example, the Directory Server uses this field to specify the operation ID it has assigned to the client request.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.2",
  "control-name":"Intermediate Client Response Control",
  "criticality":false,
  "value-json":{ "server-name":"PingDirectory",
                 "server-session-id":"conn=1234",
                 "server-request-id":"op=56" } }

The proprietary join request control can be included in a search request to indicate that each search result entry may include a corresponding join result control with information from one or more other entries that are in some way related to (for example, "joined with") that search result entry. The control has an OID of 1.3.6.1.4.1.30221.2.5.9, and it takes a value. The following fields may be present in the value-json representation of the value:

• join-rule: A mandatory JSON object field that provides the primary criteria to use when selecting entries to be joined with each search result entry. This is described in detail below.

• base-dn-type: A mandatory string field that indicates how the server should determine the base DN to use for joined entries. Only entries matching or below the join base DN (and within the join scope) may be joined with search result entries. This field must have one of the following values:

  • use-search-base-dn : Indicates that the server should use the base DN from the associated search request as the join base DN.

  • use-source-entry-dn: Indicates that the server should use the DN of the associated search result entry as the join base DN.

  • use-custom-base-dn: Indicates that the server should use the specific base DN specified in the base-dn-value field as the join base DN.

• base-dn-value: An optional string field whose value is the base DN that should be used for joined entries. This field must be present if the base-dn-type value is use-custom-base-dn; otherwise, it must be absent.

• scope: An optional string field whose value is the scope to use for joined entries. If this is not provided, then the scope from the associated search request will be used. Otherwise, it must have one of the following values (which match the allowed searchScope values in the Directory REST API):

  • baseObject: Indicates that only the entry specified as the join base DN may be joined with the search result entry.

  • singleLevel: Indicates that only entries immediately below the join base DN (but not the join base entry itself, nor any entries more than one level below it) may be joined with the search result entry.

  • wholeSubtree: Indicates that the join base entry or any of its subordinates (to any depth) may be joined with the search result entry.

  • subordinateSubtree: Indicates that any entries below the join base entry (to any depth), but not the join base entry itself, may be joined with the search result entry.

• alias-dereferencing-behavior: An optional string field whose value is the behavior to use when dereferencing any aliases encountered during join processing. Note that while the LDAP version of the join request control does allow this element to be present, the Ping Identity Directory Server does not support aliases, so it has no purpose and should generally be omitted. However, if a value is provided, then its value must be one of "neverDerefAliases", "derefInSearching", "derefInFindingBaseObj", or "derefAlways".

• size-limit: An optional integer field that specifies the maximum number of entries that may be joined with any single search result entry. If this is not specified, the size limit from the search request will be used as the join size limit. Note that the server will impose a maximum join size limit of no more than 1000 entries (and possibly smaller than that, based on resource limits in place for the requester), so the server may use a smaller size limit than the one requested by the client.

• filter: An optional string field whose value is the string representation of a search filter that entries will be required to match in order to be joined with a search result entry.

• attributes: An optional array field whose values are strings that represent the names of the attributes that should be included in joined entries. If this field is not provided, or if its value is an empty array, then the server behaves as if all user attributes and no operational attributes had been requested.

• require-match: A mandatory Boolean field that indicates whether a search result entry will be required to be joined with one or more other entries to be included in the set of search results. If this field has a value of true, then a search result entry that is not joined with any other entries will not be returned to the client. If this field has a value of false, then search result entries that match the original search request criteria may be returned even if they are not joined with any other entries.

• nested-join: An optional JSON object field that may be used to specify nested join criteria, in which each joined entry may itself be joined with other entries. If this is specified, then the fields of this JSON object are the same as those that may be used in the value-json element (including another nested-join field if desired).

The main criteria used to identify entries that should be joined with each search result entry is specified using the join rule. The supported join rule types are:

• DN Join: Indicates that the search result entry includes an attribute whose values are the DNs of the entries to be joined with it. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For a DN join, the value must be "dn".

  • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry whose values are the DNs of the entries to be joined with that entry.

• Reverse DN Join: Indicates that the entries to be joined with a search result entry include an attribute in which one of the values is the DN of the search result entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For a reverse DN join, the value must be "reverse-dn".

  • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined in which one of the values is the DN of the source entry.

• Equality Join: Indicates that the entries to be joined with a search result entry must include an attribute with a value that matches the value of a corresponding attribute in the source entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For an equality join, the value must be "equality".

  • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry that must have at least one value that matches a value in the target attribute.

  • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined that must match at least one value from the source attribute.

  • match-all: A mandatory Boolean field that indicates how to handle multi-valued source attributes. If this field has a value of true, then an entry will be joined with the source entry only if the target attribute contains all of the values of the source attribute. If it has a value of false, then an entry may be joined with the source entry as long as at least one of the values of the source attribute is present in the target attribute.

• Contains Join: Indicates that the entries to be joined with a search result entry must include an attribute with a value that contains (or is equal to) a value from a corresponding attribute in the source entry. That is, at least one value from an attribute in the source entry must be a substring of a value of a specified attribute in the target entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For a contains join, the value must be "contains".

  • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry that must have at least one value that matches or is a substring of a value in the target attribute.

  • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined that must contain at least one value that matches or contains a substring that matches a value from the source entry.

  • match-all: A mandatory Boolean field that indicates how to handle multi-valued source attributes. If this field has a value of true, then an entry will be joined with the source entry only if the target attribute contains has values in which all of the source attribute values are present as substrings. If this field is absent, or if it is present with a value of false, then an entry may be joined with the source entry as long as at least one of the values of the target attribute contains at least one of the values of the source attribute as a substring.

• AND Join: Indicates that the entries to be joined with a search result entry must match multiple sets of nested join rules. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For an AND join, the value must be "and".

  • rules: A mandatory, non-empty array field whose values are JSON objects that represent the nested join rules that will all be required to match a given entry for that entry to be joined with the source entry.

• OR Join: Indicates that the entries to be joined with a search result entry must match at least one of a given set of nested join rules. If this type of join is to be used, then the join-rule JSON object may include the following fields:

  • type: A mandatory string field that indicates the join rule type. For an OR join, the value must be "or".

  • rules: A mandatory, non-empty array field whose values are JSON objects that represent the nested join rules of which at least one must match a given entry for that entry to be joined with the source entry.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.9",
    "control-name":"Join Request Control",
    "criticality":false,
    "value-json": { 
        "join-rule": { 
            "type":"dn",
            "attribute":"manager" 
        },
        "base-dn-type":"use-custom-base-dn",
        "base-dn-value":"ou=People,dc=example,dc=com",
        "scope":"wholeSubtree",
        "size-limit":10,
        "attributes": [ 
            "givenName",
            "sn",
            "cn",
            "mail"
        ],
        "require-match":false
    } 
}

This control can be included in a search result entry in response to a join request control in order to provide a set of entries that are related to that search result entry. The control has an OID of 1.3.6.1.4.1.30221.2.5.9, and it takes a value. The following fields may be present in the value-json representation of the value:

• result-code: An integer field whose value is the numeric representation of the LDAP result code for the join processing.

• matched-dn: An optional string field that can be used to provide a matched DN for the join processing. If the join base entry does not exist, this may be the closest ancestor to that entry that actually does exist.

• diagnostic-message: An optional string field that can be used to provide additional information about the join processing.

• referral-urls: An optional array field whose values are strings that represent referral URLs encountered while resolving the join base entry.

• joined-entries: An array field whose values are JSON objects that represent entries that were joined with the search result entry. The format of these JSON objects is essentially the same as the format used for search result entries in the Directory REST API, with the string "_dn" field used to hold each entry's DN, and a separate string array field for each attribute in the entry. If there are nested join results, then the "_nested-join-results" array field may provide a set of JSON objects whose values are the entries joined with that join entry, using the same fields as the joined-entries field (including another "_nested-join-results" field, if appropriate).

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.9",
  "control-name":"Join Result Control",
  "criticality":false,
  "value-json":{ "result-code":0,
                 "joined-entries":[ { "_dn":"uid=jdoe,ou=People,dc=example,dc=com",
                                      "uid":[ "jdoe" ],
                                      "givenName":[ "John" ],
                                      "sn":[ "Doe" ],
                                      "cn":[ "John Doe" ],
                                      "mail":[ "jdoe@example.com" ] } ] } }

The standard ManageDsaIT request control can be included in requests to indicate that the server should treat smart referral entries as regular entries rather than generating referrals or search result references from them. The control has an OID of 2.16.840.1.113730.3.4.2, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"2.16.840.1.113730.3.4.2",
    "control-name":"ManageDsaIT Request Control",
    "criticality":false
}

The standard matched values request control can be included in search requests to indicate that the server should only return values for a specified attribute that match a given filter, instead of returning all values for that attribute. The control has an OID of 1.2.826.0.1.3344810.2.3, and it takes a value. The following fields may be present in the value-json representation of the value:

• filters: A mandatory, non-empty array field whose values are the string representations of the matched values filters to use. A matched values filter is very similar to a regular LDAP filter, except that the AND, OR, and NOT filter types cannot be used, and the extensible match filter type cannot use the dnAttributes element.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.2.826.0.1.3344810.2.3",
    "control-name":"Matched Values Request Control",
    "criticality":false,
    "value-json": { 
        "filters": [ 
            "(mail=*@example.com)" 
        ] 
    } 
}

The proprietary matching entry count request control may be included in a search request to indicate that instead of returning the set of matching entries, it should instead return a result with a response control that provides an estimate of the number of matching entries, along with potential debug information describing how the server used indexes to arrive at that result. The control has an OID of 1.3.6.1.4.1.30221.2.5.36, and it takes a value. The following fields may be present in the value-json representation of the value:

• maximum-candidates-to-examine: An optional integer field whose value is the maximum number of entries that the server should retrieve and examine to determine whether they actually match the search criteria and whether they would be returned to the client in a normal search operation. If this is not provided, then a default value of zero is used.

• always-examine-candidates: An optional Boolean field that indicates whether the server should always examine candidate entries to determine whether they would actually be returned to the client (for example, that the requester has permission to retrieve those entries), even if the search is fully indexed and the server knows that all of the candidates match the search criteria. If this is not provided, then a default value of false is used.

• process-search-if-unindexed: An optional Boolean field that indicates whether the server should actually process the search to identify the set of matching entries if the search is completely unindexed. If this is not provided, then a default value of false is used.

• include-debug-info: An optional Boolean field that indicates whether the server should include debug information in the response that provides additional details about the processing it performed to arrive at that result. If this is not provided, then a default value of false is used.

• skip-resolving-exploded-indexes: An optional Boolean field that indicates whether the server should not resolve exploded indexes in cases where the size of the ID set is known. This can reduce the time required to obtain the final result, but that result may be less accurate. If this is not provided, then a default value of false is used.

• fast-short-circuit-threshold: An optional integer field whose value is the short-circuit threshold that the server should use for "fast" filter components (those in which the server may need to only examine a single index key, like presence, equality, and approximate-match components). If this is not provided, the server automatically chooses an appropriate threshold.

• slow-short-circuit-threshold: An optional integer field whose value is the short-circuit threshold that the server should use for "slow" filter components (those that are not considered "fast" and may require examining multiple index keys, like substring, greater-or-equal, and less-or-equal components). If this is not provided, the server automatically chooses an appropriate threshold.

• include-extended-response-data: An optional Boolean field that indicates whether the server should include additional information in the response, like whether all of the identified candidates are known to be within the scope of the search and which components of the filter may not have been evaluated. If this is not provided, then a default value of false is used.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.36",
    "control-name":"Matching Entry Count Request Control",
    "criticality":true,
    "value-json": { 
        "maximum-candidates-to-examine":10000,
        "include-debug-info":true
    }
}

This control may be included in a search result in response to a matching entry count request control, and it includes the results of the matching entry count processing. The control has an OID of 1.3.6.1.4.1.30221.2.5.37, and it takes a value. The following fields may be present in the value-json representation of the value:

• count-type: A string field whose value will be used to indicate how accurate the entry count is. The value may be one of the following:

  • examined-count: Indicates that the provided entry count is known to accurately represent the number of matching entries that would actually be returned to the client.

  • unexamined-count: Indicates that the provided entry count is known to accurately represent the number of matching entries, but that those entries were not examined to verify that they would all actually have been returned to the client in the course of processing a normal search (for example, because the client didn't have permission to see them, or because they are special types of entries like LDAP subentries that aren't normally returned).

  • upper-bound: Indicates that the provided entry count represents the maximum number of entries that may match the search criteria, but that the actual matching entry count could be lower.

  • unknown: Indicates that the server was unable to provide any kind of estimate for the number of entries matching the search criteria.

• count-value: An optional integer field that represents the entry count estimate determined by the server. This will be present for count-type values of examined-count, unexamined-count, and upper-bound, but will be absent for a count-type value of unknown.

• search-indexed: A Boolean field that indicates whether the server considers the search to be at least partially indexed.

• fully-indexed: An optional Boolean field that indicates whether the server considers the search to be fully indexed. This will only be present if extended response information was requested.

• short-circuited: An optional Boolean field that indicates whether the server short-circuited at any point in evaluating the search criteria. This will only be present if extended response information was requested.

• candidates-are-in-scope: An optional Boolean field that indicates whether the server knows that all candidate entries are within the scope of the search. This will only be present if extended response information was requested.

• remaining-filter: An optional string field whose value is the portion of the provided search filter that was not evaluated during the course of coming up with the estimate. This will only be present if extended response information was requested and a remaining filter is available.

• debug-info: An optional array field whose values are strings providing debug messages generated by the server in the course of determining the estimated number of matching entries. This will only be present if debug information was requested.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.37",
  "control-name":"Matching Entry Count Response Control",
  "criticality":false,
  "value-json":{ "count-type":"unexamined-count",
                 "count-value":1,
                 "search-indexed":true,
                 "debug-info":[ "Sample debug message 1",
                                "Sample debug message 2" ] } }

The proprietary name with entryUUID request control may be included in an add request to indicate that the server should replace the RDN of the DN included in the request with the server-generated entryUUID for that entry. The control has an OID of 1.3.6.1.4.1.30221.2.5.44, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.44",
    "control-name":"Name With entryUUID Request Control",
    "criticality":true 
}

The standard (but not yet ratified and assigned an official OID) no operation request control may be included in an add, delete, modify, or modify DN request to indicate that the server should perform as much processing for the operation as possible to determine whether it would succeed, but that it should not actually apply any changes to the data. The control has an OID of 1.3.6.1.4.1.30221.2.5.44, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.4203.1.10.2",
    "control-name":"No Operation Request Control",
    "criticality":true
}

The proprietary operation purpose request control may be included in a request to provide additional information about the reason for that request. It is purely informational (for example, for inclusion in access log messages generated for the operation), and does not otherwise affect the server's processing for that operation. The control has an OID of 1.3.6.1.4.1.30221.2.5.19, and it takes a value. The following fields may be present in the value-json representation of the value, and at least one of the fields must be present:

• application-name: An optional string field whose value is the name of the application that generated the request.

• application-version: An optional string field whose value is the version for the application that generated the request.

• code-location: An optional string field whose value indicates the location in the application code in which the request was generated.

• request-purpose: An optional string field that contains a message with the purpose for the request.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.19",
    "control-name":"Operation Purpose Request Control",
    "criticality":false,
    "value-json": { 
        "application-name":"My LDAP-Enabled Application",
        "application-version":"1.2.3",
        "code-location":"authenticateUser",
        "request-purpose":"Validating the provided credentials"
    } 
}

The proprietary password update behavior request control may be included in an add, modify, or password modify extended request to override certain behaviors that the server would otherwise use when updating a user's password. The control has an OID of 1.3.6.1.4.1.30221.2.5.51, and it takes a value. The following fields may be present in the value-json representation of the value:

• is-self-change: An optional Boolean field that may be used to override the server's default determination about whether the password update represents a self change or an administrative reset. If this is not specified, the server will determine whether it is a self-change.

• allow-pre-encoded-password: An optional Boolean field that may be used to override the server's default determination about whether to accept a new password that has been pre-encoded rather than provided in the clear. If this is not specified, the server uses the configuration to determine whether pre-encoded passwords should be allowed.

• skip-password-validation: An optional Boolean field that may be used to indicate whether the server should skip the normal password validation processing when determining whether to accept the new password. If this is not specified, the server uses the configuration to determine whether to perform password validation.

• ignore-password-history: An optional Boolean field that may be used to indicate whether the server should ignore the user's password history when determining whether to accept the new password. If this is not specified, the server uses the configuration to determine whether to ignore the password history.

• ignore-minimum-password-age: An optional Boolean field that may be used to indicate whether the server should ignore any minimum password age constraint in effect for the user. If this is not specified, the server uses the configuration to determine whether to ignore the minimum password age.

• password-storage-scheme: An optional string field whose value is the name of the password storage scheme that should be used to encode the new password. If this is not specified, the server uses the configuration to determine which password storage scheme(s) to use.

• must-change-password: An optional Boolean field that may be used to override the server's default determination about whether the user is required to choose a new password the next time they authenticate. If this is not specified, the server uses the configuration to determine whether to force a password change.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.51",
    "control-name":"Password Update Behavior Request Control",
    "criticality":false,
    "value-json": { 
        "is-self-change":true,
        "must-change-password":false
    } 
}

The proprietary password validation details request control may be included in an add, modify, or password modify extended request to indicate that the server should return a response control with information about the requirements imposed for the new password and which of those requirements were satisfied. The control has an OID of 1.3.6.1.4.1.30221.2.5.40, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.40",
    "control-name":"Password Validation Details Request Control",
    "criticality":false 
}

This control may be included in an add, modify, or password modify extended response in request that included a password validation request control, and it may provide details about the validation performed on the proposed password. The control has an OID of 1.3.6.1.4.1.30221.2.5.41, and it takes a value. The following fields may be present in the value-json representation of the value:

• response-type: A string field that indicates the result of the password validation processing for the attempt. The value will be one of the following:

  • validation-performed: Indicates that the server performed validation processing for the proposed new password.

  • no-password-provided: Indicates that the request did not include a new password to be validated.

  • multiple-passwords-provided: Indicates that the request included multiple new passwords. This control may only be used in cases where a single new password is provided.

  • no-validation-attempted: Indicates that the server did not attempt any validation for the new password (for example, because it was an administrative password reset and the server has been configured to skip password validation for administrative resets).

• validation-details: An optional array field whose values are JSON objects with information about the types of validation performed for the new password. The fields that may be present in these JSON objects include:

  • password-quality-requirement: A JSON object field whose value provides information about a password quality requirement that was evaluated. The fields that may be present in these JSON objects include:

    • description: A string field whose value is a user-friendly description of the requirement that the proposed new password is expected to satisfy.

    • client-side-validation-type: An optional string field whose value is an identifier that the client can use to determine what type of validation is being performed. The client may use this information to attempt client-side validation of the password so that known-bad passwords can be rejected without needing to interact with the server.

    • client-side-validation-properties: An optional array field whose values are JSON objects with additional properties that are associated with the validation. Each of these JSON objects will include a "name" field with the property name and a "value" field with the property value.

  • requirement-satisfied: A Boolean field that indicates whether the provided new password satisfied the associated requirement.

  • additional-information: An optional string field with additional information about the validation for the associated requirement.

• missing-current-password: A Boolean field that indicates whether the server requires the user's current password to be provided as part of a password change, but that password was not provided. If this is false, then it indicates that either the user's current password was provided or that it was not required.

• must-change-password: A Boolean field that indicates whether the user will be required to choose a new password the next time they authenticate.

• seconds-until-expiration: An optional integer field whose value is the number of seconds until the user's password expires.

The following represents an example JSON encoding for the control:

{ 
  "oid":"1.3.6.1.4.1.30221.2.5.41",
  "control-name":"Password Validation Details Response Control",
  "criticality":false,
  "value-json":
  { 
    "response-type":"validation-performed",
    "validation-details":
    [ 
      { 
        "password-quality-requirement":
        { 
          "description":"The new password must be at least 10 characters long.",
          "client-side-validation-type":"length",
          "client-side-validation-properties":
          [ 
            { 
              "name":"min-password-length",
              "value":"10"
            }
          ],
        },
        "requirement-satisfied":true
      },
      { 
        "password-quality-requirement":
        { 
          "description":"The new password must not match the current password.",
          "client-side-validation-type":"not-current-password" 
        },
        "requirement-satisfied":true
      }
    ],
    "missing-current-password":false,
    "must-change-password":false,
    "seconds-until-expiration":7776000
  }
}

The permissive modify request control (which isn't a standard control, having originated in Active Directory, but is supported in a few types of directory servers) may be included in a modify request to indicate that the server should relax a couple of constraints that it would normally enforce for modifications. In particular, it indicates that the server should not reject an attempt to add values to an attribute when one or more of those values already exist, and that it should not reject an attempt to remove values from an attribute when one or more of those values does not exist. The control has an OID of 1.2.840.113556.1.4.1413, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.2.840.113556.1.4.1413",
    "control-name": "Permissive Modify Request Control",
    "criticality": false
}

The proprietary permit unindexed search request control may be included in a search request to indicate that the server should attempt to process it, even if the search is unindexed and could be expensive. The control has an OID of 1.3.6.1.4.1.30221.2.5.55, and it takes a value. The value-json field will hold a res

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.55",
    "control-name": "Permit Unindexed Search Request Control",
    "criticality": false 
}

The standard post-read request control may be included in an add, modify, or modify DN request to indicate that the server should return a response control with a copy of the entry as it appears immediately after the changes were applied. The control has an OID of 1.3.6.1.1.13.2, and it takes a value. The following fields may be present in the value-json representation of the value:

• attributes: An optional array field whose values are strings that represent the names of the attributes to include in the entry returned in the response control. It may also include special tokens that represent groups of attributes (for example, "*" to indicate all user attributes, or "+" to represent all operational attributes). If this field is not provided, or if it is empty, then the server responds as if all user attributes had been requested.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.1.13.2",
    "control-name": "Post-Read Request Control",
    "criticality": false,
    "value-json": {
        "attributes": [ 
            "uid",
            "givenName",
            "sn",
            "cn",
            "mail" 
        ] 
    } 
}

Theiscontrol may be included in response to an add, modify, or modify DN request that included the post-read request control, and it includes content from the target entry as it appeared with the changes applied. The control has an OID of 1.3.6.1.1.13.2, and it takes a value. The contents of the value-json object will essentially be the same as the representation of an entry in the Directory REST API, with the notable exception that all attribute values will be included in an array (even if the associated attribute type is declared single-valued in the server schema). The "_dn" field will hold the DN of the entry, and all remaining fields will represent attributes from that entry.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.1.13.2",
  "control-name":"Post-Read Response Control",
  "criticality":false,
  "value-json":{ "_dn":"uid=jdoe,ou=People,dc=example,dc=com",
                 "uid":[ "jdoe" ],
                 "givenName":[ "John" ],
                 "sn":[ "Doe" ],
                 "cn":[ "John Doe" ],
                 "mail":[ "jdoe@example.com" ] } }

The standard pre-read request control may be included in a delete, modify, or modify DN request to indicate that the server should return a response control with a copy of the entry as it appeared immediately before the changes were applied. The control has an OID of 1.3.6.1.1.13.1, and it takes a value. The following fields may be present in the value-json representation of the value:

• attributes: An optional array field whose values are strings that represent the names of the attributes to include in the entry returned in the response control. It may also include special tokens that represent groups of attributes (for example, "*" to indicate all user attributes, or "+" to represent all operational attributes). If this field is not provided, or if it is empty, then the server responds as if all user attributes had been requested.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.1.13.1",
    "control-name": "Pre-Read Request Control",
    "criticality": false,
    "value-json": { 
        "attributes":[ 
            "uid",
            "givenName",
            "sn",
            "cn",
            "mail" 
        ] 
    } 
}

This control may be included in response to a delete, modify, or modify DN request that included the pre-read request control, and it includes content from the target entry as it appeared immediately before the changes were applied. The control has an OID of 1.3.6.1.1.13.1, and it takes a value. The contents of the value-json object will essentially be the same as the representation of an entry in the Directory REST API, with the notable exception that all attribute values will be included in an array (even if the associated attribute type is declared single-valued in the server schema). The "_dn" field will hold the DN of the entry, and all remaining fields will represent attributes from that entry.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.1.13.1",
  "control-name":"Pre-Read Response Control",
  "criticality":false,
  "value-json":{ "_dn":"uid=jdoe,ou=People,dc=example,dc=com",
                 "uid":[ "jdoe" ],
                 "givenName":[ "John" ],
                 "sn":[ "Doe" ],
                 "cn":[ "John Doe" ],
                 "mail":[ "jdoe@example.com" ] } }

The standard proxied authorization V1 request control may be included in a request to indicate that the server should process that request under the authority of another user, rather than under the authority of the user currently authenticated on the connection. The control has an OID of 2.16.840.1.113730.3.4.12, and it takes a value. The following fields may be present in the value-json representation of the value:

• authorization-dn: A mandatory string field whose value is the DN of the user as whom the request should be authorized.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "2.16.840.1.113730.3.4.12",
    "control-name": "Proxied Authorization V1 Request Control",
    "criticality": true,
    "value-json": { 
        "authorization-dn": "uid=jdoe,ou=People,dc=example,dc=com"
    }
}

The standard proxied authorization V2 request control may be included in a request to indicate that the server should process that request under the authority of another user, rather than under the authority of the user currently authenticated on the connection. The control has an OID of 2.16.840.1.113730.3.4.18, and it takes a value. The following fields may be present in the value-json representation of the value:

• authorization-id: A mandatory string field whose value is an authorization ID that identifies the user as whom the request should be authorized. The authorization ID should either start with "dn:" and be followed by the DN of the user, or it should start with "u:" and be followed by a username (or some other type of identifier) for the user.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "2.16.840.1.113730.3.4.18",
    "control-name": "Proxied Authorization V2 Request Control",
    "criticality": true,
    "value-json": { 
        "authorization-id": "dn:uid=jdoe,ou=People,dc=example,dc=com"
    }
}

The proprietary purge password request control may be included in a modify or password modify extended request to indicate that the server should completely purge the former password from the user's entry, even if it would have otherwise been treated as a retired password. The control has an OID of 1.3.6.1.4.1.30221.2.5.32, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.32",
    "control-name": "Purge Password Request Control",
    "criticality": false
}

The proprietary real attributes only request control may be included in a search request to indicate that any search result entries that are returned should only include the values of real attributes from the entry, and that virtual attributes should be excluded. The control has an OID of 2.16.840.1.113730.3.4.17, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "2.16.840.1.113730.3.4.17",
    "control-name": "Real Attributes Only Request Control",
    "criticality": false
}

The proprietary reject unindexed search request control may be included in a search request to indicate that the server should not attempt to process the search if it is unindexed. The control has an OID of 1.3.6.1.4.1.30221.2.5.54, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.54",
    "control-name": "Reject Unindexed Search Request Control",
    "criticality": false
}

The proprietary retire password request control may be included in a modify or password modify request to indicate that the server should convert the user's former password to a retired password so that it may continue to be used for a limited period of time. The control has an OID of 1.3.6.1.4.1.30221.2.5.31, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.31",
    "control-name": "Retire Password Request Control",
    "criticality": false 
}

This control can be included in a delete request to hide a server entry so that it can only be retrieved with a request that includes the Soft deleted entry access request control or a filter which includes an "(objectClass=ds-soft-deleted-entry)" component. A soft-deleted entry can be restored with the same or a different DN using the Undelete request control.

The _controls array must include the value-json attribute with the return-soft-delete-response-control value, which is a mandatory boolean specifying whether the soft delete response control should be returned. This response control includes the DN of the soft-deleted entry in the soft-deleted-entry-dn attribute.

The following sample shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.20",   
    "control-name":"Soft Delete Request Control",
    "criticality":true,
    "value-json":
    {
        "return-soft-delete-response-control":true
    }
}

For a soft delete to succeed, there must be a soft delete policy created and set via the global configuration. The following commands set a basic soft delete policy.

dsconfig create-soft-delete-policy --policy-name 'Soft Delete Policy'
dsconfig set-global-configuration-prop --set 'soft-delete-policy:Soft Delete Policy'

Learn more about the following related request controls:

• Undelete request control
• Soft deleted entry access request control
• Hard delete request control

This control can be included in a search request to show soft-deleted entries in the search results. Learn more about soft deletes in Soft delete request control.

The _controls array must include the value-json attribute with the following values:

• include-non-soft-deleted-entries: A mandatory boolean specifying whether entries which have not been soft-deleted will be included in search results if they meet the criteria.

• return-entries-in-undeleted-form: A mandatory boolean specifying whether soft-deleted entries returned in search results will display as if they were undeleted (the entryUUID will not be included in the DN, and the entry won't be given the ds-soft-delete-entry object class).

The following example shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.20",   
    "control-name":"Soft-Deleted Entry Access Request Control",
    "criticality":true,
    "value-json":
    {
        "return-soft-delete-response-control":true
    }
}

The proprietary suppress referential integrity updates request control may be included in a delete or modify DN request to indicate that the server should not perform any referential integrity processing for the operation. The control has an OID of 1.3.6.1.4.1.30221.2.5.30, and it does not take a value.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.30",
    "control-name": "Suppress Referential Integrity Updates Request Control",
    "criticality": false
}

This control can be included in an add request to restore entries that have been soft-deleted and allow them to be normally accessed again. Learn more about soft deletes in Soft delete request control.

The request body must contain the following attributes in addition to the _controls array, and no other attributes can be included:

• _dn: A mandatory string specifying the new DN to be assigned to the entry once it is undeleted.

• ds-undelete-from-dn: A mandatory string specifying the full DN of the soft-deleted entry. This DN is returned in the soft-deleted-entry-dn field when an entry is soft-deleted and it can be searched with appropriate permissions.

The following example shows the JSON encoding for the control:

{ 
    "oid":"1.3.6.1.4.1.30221.2.5.23",   
    "control-name":"Undelete Request Control",
    "criticality":true
}

The proprietary uniqueness request control may be included in an add, modify, or modify DN request to indicate that the server should impose unique attribute constraints for the operation. The control has an OID of 1.3.6.1.4.1.30221.2.5.52, and it takes a value. The following fields may be present in the value-json representation of the value:

• uniqueness-id: An optional string field that holds a unique identifier for this control instance. This is intended to help distinguish between multiple uniqueness request controls in the same operation, and each response control includes the uniqueness ID of the associated request control. If this is not provided, a uniqueness ID is automatically generated.

• attribute-types: An optional array field whose values are the names of the attribute types for which to impose uniqueness. It may be empty or absent if uniqueness should only be enforced using a filter.

• multiple-attribute-behavior: An optional string field whose value indicates the behavior that should be used if multiple unique attribute types are specified. It may be absent if only a single attribute type is requested, or if the default behavior should be used. If it is present, then the value should be one of the following strings:

  • unique-within-each-attribute: Indicates that the server should treat each of the configured attribute types separately. This is the default behavior that is used if this field is not specified.

  • unique-across-all-attributes-including-in-the-same-entry: Indicates that the server should flag any case in which any entry has a conflicting value in any of the configured attribute types, including in cases in which the same value appears in multiple attributes within the same entry.

  • unique-across-all-attributes-except-in-the-same-entry: Indicates that the server should flag any case in which any entry has a conflicting value in any of the configured attribute types, with the exception that conflicts will be permitted across different attributes in the same entry.

  • unique-in-combination: Indicates that the server should flag any case in which another entry has the same combination of values for all of the configured attribute types.

• base-dn: An optional string field whose value is the base DN that is used for searches used to identify uniqueness conflicts. If this is not specified, then the server performs the searches below all public naming contexts.

• filter: An optional string field whose value is the string representation of a search filter that is used to identify uniqueness conflicts.

• prevent-conflicts-with-soft-deleted-entries: An optional Boolean field that indicates whether the server should consider soft-deleted entries when looking for conflicts. If this is true, then any conflicts within soft-deleted entries are reported. If it is false, or if this field is not provided, then any conflicts in soft-deleted entries are ignored.

• pre-commit-validation-level: A mandatory string field whose value indicates the level of validation the server should perform before attempting to apply the change. The value may be one of the following:

  • none: Indicates that the server should not attempt any pre-commit validation.

  • all-subtree-views: Indicates that the server should check all applicable subtree views. If the request is passing through a Directory Proxy Server, it is possible that only a single server is examined for potential conflicts.

  • all-backend-sets: Indicates that if the request is passing through a Directory Proxy Server that uses entry balancing, then a search for conflicts should be performed in one server in each of the applicable backend sets.

  • all-available-backend-servers: Indicates that if the request is passing through a Directory Proxy Server, then a search for conflicts should be performed in all available backend servers in all applicable backend sets.

• post-commit-validation-level: An mandatory string field whose value indicates the level of validation the server should perform after successfully applying the change, to see if a conflict may have arisen as a result of another operation that was processed concurrently. The set of allowed values for this field are the same as the allowed values for the pre-commit-validation-level field.

• alert-on-post-commit-conflict-detection: An optional Boolean field that indicates whether the server should raise an administrative alert if a conflict was detected during post-commit validation. If this is not specified, a default value of true is used.

• create-conflict-prevention-details-entry: An optional Boolean field that indicates whether the server should create a temporary entry that can improve the server's ability to detect conflicts before they happen, albeit with more expensive processing. If this is not specified, a default value of false is used.

The following sample shows the JSON encoding for the control:

{ 
    "oid": "1.3.6.1.4.1.30221.2.5.52",
    "control-name": "Uniqueness Request Control",
    "criticality": true,
    "value-json": { 
        "uniqueness-id": "Ensure uid and mail are separately unique",
        "attribute-types": [ 
            "uid",
            "mail"
        ],
        "multiple-attribute-behavior": "unique-within-each-attribute",
        "base-dn": "ou=People,dc=example,dc=com",
        "prevent-conflicts-with-soft-deleted-entries": false,
        "pre-commit-validation-level":"all-available-backend-servers",
        "post-commit-validation-level": "all-backend-sets",
        "alert-on-post-commit-conflict-detection": true,
        "create-conflict-prevention-details-entry": true
    }
}

This control may be included in the response to an add, modify, or modify DN request that included the uniqueness request control. The control has an OID of 1.3.6.1.4.1.30221.2.5.53, and it takes a value. The following fields may be present in the value-json representation of the value:

• uniqueness-id: A string field that holds the uniqueness ID from the uniqueness request control with which this response control is associated.

• pre-commit-validation-passed: An optional Boolean field that indicates whether pre-commit validation passed without identifying any conflicts.

• post-commit-validation-passed: An optional Boolean field that indicates whether post-commit validation passed without identifying any conflicts.

• validation-message: An optional string field that provides a message with additional information about the uniqueness processing.

The following represents an example JSON encoding for the control:

{ "oid":"1.3.6.1.4.1.30221.2.5.53",
  "control-name":"Uniqueness Response Control",
  "criticality":false,
  "value-json":{ "uniqueness-id":"Ensure uid and mail are separately unique",
                 "pre-commit-validation-passed":true,
                 "post-commit-validation-passed":true } }

The proprietary virtual attributes only request control may be included in a search request to indicate that any search result entries that are returned should only include the values of virtual attributes generated for the entry, and that real attributes should be excluded. The control has an OID of 2.16.840.1.113730.3.4.19, and it does not take a value.

The following sample shows the JSON encoding for the control:

{
    "oid": "2.16.840.1.113730.3.4.19",
    "control-name": "Virtual Attributes Only Request Control",
    "criticality": false
}

Directory REST API requests

Authorization

To make a call to the Directory REST API, you can use basic authentication (username/password) or an OAuth 2.0 access token for API authentication. The access token, shown here as accessToken, is accepted per RFC 6750 through the Authorization HTTP request header. For more information about acquiring a bearer access token for your organization, see Getting started.

HTTP methods

The Directory REST API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED error in the response.

• POST

  Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.

• PUT

  Updates attribute values specified by the user for the identified resource. Unspecified attributes are ignored.

• PATCH

  Updates only the attribute values specified by the user for the identified resource. Unspecified attributes are ignored.

• GET

  Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.

• DELETE

  Deletes or unlinks a resource from the collection.

Updating a resource

Requests submitted using PUT update attribute values of the resource specified in the request. You can explicitly clear an entry by specifying null for the attribute or by specifying an empty array in the case of multi-value attributes.

Partial updates to a resource

A PATCH operation performs updates of a resource, similar to that of a PUT operation. In addition, it allows updates to one item in a multi-value attribute. Omitting an attribute in a PATCH operation results in the attribute being ignored.

For set actions, you can use a value of null to explicitly clear the value. For remove actions, you must specify the value to remove.

Supported data exchange formats

The Directory REST API supports JSON as the data exchange format. The Content-type request header for the API call identifies the format of the request body for PUT, POST, and PATCH operations. The following sample identifies JSON as the data exchange type:

curl -X PATCH "https://ds.example.com/directory/v1/{dn}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
  "param1" : "value1",
  "param2" : "value2",
}"

Link expansion

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request. The allowed values for the expand parameter are found in a resource's _links field (not including "self"). Unrecognized values are ignored. Multiple values are separated using the comma character.

Here is a sample request that uses the expand parameter to provide an inline representation of the manager resource in the _embedded field.

GET /directory/v1/uid=example.user,ou=people,dc=example,dc=com?expand=manager

The response data looks like this:

{
    "_dn": "uid=example.user,ou=People,dc=example,dc=com",
    "_embedded": {
        "manager": {
            "_dn": "uid=manager,ou=People,dc=example,dc=com",
            "cn": ["Manager User"],
            "givenName": ["Manager"],
            "objectClass": [
                "top",
                "person",
                "organizationalPerson",
                "inetOrgPerson"
            ],
            "sn": ["User"],
            "uid": ["manager"]
        }
    },
    "_links": {
        "manager": {
            "href": "https://ds.example.com/directory/v1/uid=manager,ou=people,dc=example,dc=com"
        },
        "schemas": [
            {
                "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson"
            }
        ],
        "self": {
            "href": "https://ds.example.com/directory/v1/uid=example.user,ou=People,dc=example,dc=com"
        }
    },
    "cn": ["Example User"],
    "givenName": ["Example"],
    "manager": ["uid=manager,ou=people,dc=example,dc=com"],
    "objectClass": [
        "top",
        "person",
        "organizationalPerson",
        "inetOrgPerson"
    ],
    "sn": ["User"],
    "uid": ["example.user"]
}

Directory REST API responses

HTTP response headers

The Directory REST API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

• Access-Control-Allow-Headers

  This header is used in response to a preflight request to indicate that HTTP headers can be used when making a request.

• Access-Control-Allow-Max-Age

  This header specifies how long the results of a preflight request can be cached.

• Access-Control-Allow-Methods

  This header specifies specifies the method or methods allowed when accessing the resource in response to a preflight request.

• Content-Type

  This header specifies the data exchange format for the response data. The value is application/HAL+json for successful operations and application/json for errors.

• Date

  This header specifies the date the response was sent.

HTTP response codes

The Directory REST API returns the status of an operation as a registered HTTP response code. The HTTP response codes are:

• 200-299

  Confirms a successful call.

• 300-399

  Indicates that the call or subsequent calls should be made to another resource.

• 400-499

  Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.

• 500-599

  Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

Operations may also return additional information about a failed operation in the HTTP response body.

Synchronous responses

Responses for synchronous operations have the following behavior:

• GET operations

  A request that returns a body also returns the code 200 OK with the resource in the body of the response.

• POST operations

  A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource. A POST operation that does not create a resource, such as POST /directory/v1/{dn}/subtree/search, returns a 200 OK message.

• PUT or PATCH operations

  A request that updates a resource returns 200 OK and the full resource in the body.

• DELETE operations

  A request that deletes a resource returns 204 NO CONTENT and no body.

Response data structure

All Directory REST API endpoints return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the Directory REST API result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.

{
    "size": 3,
    "_links": {
        "self": {
            "href": "https://<server>//directory/v1/schemas"
        }
    },
    "_embedded": {
        "schemas": [
            {
                "id": "5caa81af-ec05-41ff-a709-c7378007a99c",
                "name": "SchemaName",
                "description": "Schema 1 description",
              }
          ...

For collections, the result data returns a size attribute, and all API requests return a self URL under the _links attribute that identifies the URI of the main resource. The _embedded attribute lists all the results in the collection.

These relationships and references are represented as follows:

• Links are represented using JSON HAL conventions (such as, in a _links object).

• Links are represented as absolute URLs.

• Links can be expanded using the expand parameter. The links can also be referenced via the "property-as-resource" pattern.

• References as attributes have an id value and may also have additional attributes.

Errors

Errors generated by the Directory REST API provide high-level information about the error, including an id, code, and the error message. Error responses also include a details attribute that provides specific information about one or more errors that occurred with the request. The response payload is formatted as follows:

{
   "id": "4ffa81af-ec05-41ff-a709-c7378007a99c",
   "code": "INVALID_DATA",
   "message": "Errors occurred while processing the request",
   "details": [
       {
           "code": "REQUEST_FAILED",
           "message": "Entry 'cn=Linda MissingFieldSN,ou=people,dc=example,dc=com' violates the Directory Server schema configuration because it is missing attribute 'sn' which is required by object class 'person'"
       }
   ]
}

Filtering collections

Requests that are known to return a large number of items can be filtered using the filter query string parameter. The following SCIM protocol filtering operators are supported.

For more information about the SCIM Protocol Specification, see SCIM Filtering.

curl -X "POST" "https://ds.example.com/directory/v1/ou=people,dc=example,dc=com/subtree/search" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer accessToken' \
-d $'{
  "filter": "objectClass eq \"person\" and sn eq \"Jones\"",
  "searchScope": "wholeSubtree",
  "limit": 20,
  "includeAttributes": "*,_operationalAttributes",
  "excludeAttributes": "sn,isMemberOf"
}'

Attribute tagging rules

An LDAP attribute description that uses tagging options should be treated as a subtype of the same attribute type without the tagging option, inheriting from any parent attribute types. For example, cn;region1 would be a subtype of cn and also of name since cn is a subtype of name. Likewise, cn;region2 would be a different subtype of cn and name. The combined attribute description (the attribute type and tagging options) is not declared explicitly in the directory schema; only the attribute type is declared.

Reject tagging options on _dn attributes and associated naming attribute

The Directory REST API does not allow tagging options in the _dn attribute or associated naming attribute, since the Ping Directory Server does not support this for the underlying LDAP entries. If tagging is attempted, it returns a Code: 34 (invalid DN syntax) error.

{
  "_dn": "uid;x-opt=lindajones,oupeople,dc=example,dc=com",
  "uid;x-opt": "lindajones",
}

Representation of user attributes with tagging options

User attributes with tagging options appear in a separate JSON field from other attributes with the same type but different (or no) options.

If there are multiple values with the same attribute type and tagging options, they will be represented as a JSON array.

Using POST to create a new entry containing tagged attributes

Tagged attributes are translated correctly into LDAP entries, including various permutations of the following:

• Single-valued attributes of all supported types (string, integer, boolean, JSON), with no tagging option.

• Multi-valued attributes of all supported types (string, integer, boolean, JSON), with no tagging option.

• Single-valued attributes of all supported types (string, integer, boolean, JSON), tagged with a single option.

• Multi-valued attributes of all supported types (string, integer, boolean, JSON), tagged with a single option.

• Single-valued attributes of all supported types (string, integer, boolean, JSON), tagged with multiple options.

• Multi-valued attributes of all supported types (string, integer, boolean, JSON), tagged with multiple options.

Using GET or POST/subtree /search to retrieve existing entries containing tagged attributes

Tagged attributes are translated correctly from LDAP entries, covering the same permutations for POST.

Tagged attributes are returned correctly when returning multiple entries with the /subtree option. Tagged attributes are returned correctly for multiple entries with a cursored search option.

Query parameter filtering

Note that the SCIM filter syntax (section 3.4.2.2) does not allow semicolons in attribute names. The PingDirectory REST API supports the variant syntax 'REST API Filter syntax' (which is the SCIM filter syntax plus semicolons).

If a filter clause specifies an attribute name with no tagging options, the filter applies to all attributes with that base name, tagged or untagged.

If a filter clause specifies an attribute name with tagging options, the filter applies only to attributes with that base name and all of the specified tagging options.

As specified in RFC 7644, if the specified attribute in a filter expression is a multi-valued attribute, the filter matches if any of the values of the specified attribute match the specified criterion.

• eq: Matches if any applicable attribute has a value identical to the specified one.

• ne: Matches if any applicable attribute has a value not identical to the specified one.

• co, sw, ew: Matches if any applicable attribute has a value containing the specified substring, prefix, or suffix, respectively.

• gt, ge, lt, le: Matches if any applicable attribute has a value greater than (or less than) the specified value.

Query parameters 'includeAttributes' and 'excludeAttributes'

Similarly, if the includeAttributes or excludeAttributes parameters specify an attribute name with no tagging options, the result includes or excludes all attributes of that type, tagged or untagged. If the query parameter specifies an attribute name with tagging options, the result includes or excludes only attributes with that exact name and tagging options.

Using PUT to modify An existing entry containing tagged attributes

Attributes modified using a PUT request should be specified using the exact name and tagging options. For example, the following only updates the value of myAttr and not myAttr;x-opt-1, or any other tagged attribute.

PUT /directory/v1/uid=lindajones,ou=people,dc=example,dc=com
    Content-Type: application/json
    Request Body
    {
      "myAttr": "new value for myAttr with no tagging options"
    }

Likewise, the following only updates the value of myAttr;x-opt-2;x-opt-3 and not any of the others.

PUT /directory/v1/uid=lindajones,ou=people,dc=example,dc=com
    Content-Type: application/json
    Request Body
    {
      "myAttr;x-opt-2;x-opt-3": "new value for myAttr with x-opt-2 and x-opt-3"
    }

Using PATCH to modify existing entries containing tagged attributes

Attributes to be updated using a PATCH request should be specified using the exact name and tagging options in the attributeName field.

For PATCH "add" and "remove", only attributes with the exact name and tagging options are affected. However, using PATCH "set" with an untagged attribute name removes any tagged attributes.

LDAP is an extensible protocol and can modify specifications through extended operations. The Directory REST API currently supports the following extended operations:

• Deliver one time password

• Deregister YubiKey OTP device

• Generate password

• Generate TOTP shared secret

• Get password quality requirements

• Password Modify

• Register YubiKey OTP device

• Revoke TOTP shared secret

The deliver one-time password extended operation is used to indicate that the server should generate a one-time password for a user, store it in the user's entry, and deliver it to the user through a method like email or SMS. This operation is heavily based on the DeliverOneTimePasswordExtendedRequest class in the LDAP SDK.

The request body is a JSON object with the following fields:

• dn

  An optional string field whose value is the full DN of the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

• username

  An optional string field whose value is the username for the user that is attempting to authenticate. Exactly one of the dn and username fields must be present.

• staticPassword

  A mandatory string field whose value is the static password for the target user.

• preferredDeliveryMechanisms

  An optional string array field whose values are the names of the OTP delivery mechanisms that the client wants to use, in order from most preferred to least preferred. The names that are available for use depends on the server's configuration. If this is not provided, then the server will automatically choose a delivery mechanism for the user.

The response body is created from the deliver one-time password extended result. The response is a JSON object with the following fields:

• resultCode

  A mandatory JSON object that contains the following fields:

  • value — The integer value for the LDAP result code. This is required.

  • name — A name for the LDAP result code. This is optional but recommended.

• diagnosticMessage

  An optional string field that holds a human-readable message with additional information about the operation.

• deliveryMechanism

  An optional string field that holds the name of the delivery mechanism that was used to send the one-time password to the user. This will be present if the one-time password was successfully sent.

• recipientDN

  An optional string field that holds the DN of the user for whom the password was generated and delivered. This will be present if the one-time password was successfully sent.

• recipientID

  An optional string field that holds the delivery mechanism-specific identifier to which the one-time password was sent, like an email address if the password was delivered via email or a mobile phone number of the password was delivered by SMS. This will be present if the one-time password was successfully sent, and if the delivery mechanism used to send it provided a recipient ID.

• deliveryMessage

  An optional string field that holds a message that may provide additional information about the one-time password delivery attempt.

The deregister YubiKey OTP device extended operation can be used to remove a YubiKey device from a user's account so that the user may no longer use that device to authenticate. This operation is heavily based on the DeregisterYubiKeyOTPDeviceExtendedRequest class in the LDAP SDK.

The request body is a JSON object with the following fields:

• staticPassword

  An optional string field whose value is the static password for the user. If this is provided, then the POST request will not require an Authorization header, as the request will be authorized as the end user. If this is absent, then the request must have an Authorization header, and its associated identity will be used to authorize the request.

• otp

  A mandatory string field whose value is a one-time password generated by the YubiKey device to be deregistered from the user's account.

The response body is a JSON object with the following fields:

• resultCode

  A mandatory JSON object that contains the following fields:

  • value — The integer value for the LDAP result code. This is required.

  • name — A name for the LDAP result code. This is optional but recommended.

• diagnosticMessage

  An optional string field that holds a human-readable message with additional information about the operation.

The Generate Password extended operation is not a standard LDAP operation and has been developed internally for use within PingDirectory products. Its implementation in the Directory REST API is based on the existing GeneratePasswordExtendedRequest, GeneratePasswordExtendedResult, and GeneratePasswordExtendedOperationHandler classes in the UnboundID LDAP SDK. The API method serves as a translation layer between the client's HTTP request and Directory's internal LDAP operations.

For more information on the LDAP Generate Password extended operation, see GeneratePasswordExtendedRequest. Its OID is 1.3.6.1.4.1.30221.2.6.62.

The Generate Password Extended Operation Handler Configuration

This API method acts as a layer between the client and the generate password extended operation handler that performs the internal LDAP extended operation. This handler offers the following configuration options:

• default-password-policy

  An optional, single-valued aggregation property that specifies the default password policy for requests that do not specify a password policy. If this is not specified, then the default password policy specified in the global configuration is used.

• default-password-generator

  A required, single-valued aggregation property that specifies the password generator to use if the requested password policy is not configured with a password generator.

• maximum-passwords-per-request

  An optional, single-valued integer property that specifies the maximum number of passwords that may be generated and returned for a single request. If this is not specified, a default value of 10 will be used.

• maximum-validation-attempts-per-password

  An optional, single-valued integer property that specifies the maximum number of validation attempts that should be allowed for each generated password. If this is not specified, a default value of 5 will be used.

The generate TOTP shared secret extended operation is heavily based on the GenerateTOTPSharedSecretExtendedRequest class in the LDAP SDK. This operation causes the server to generate a TOTP shared secret for a user, stores it in that user's entry, and returns it to the client so that it may be provided to an authenticator application that will generate the time-based one-time password.

The request body is a JSON object with the following field:

• staticPassword

  An optional string field whose value is the static password for the user. If this is provided, then the POST request will not require an Authorization header, as the request will be authorized as the end user. If this is absent, then the request must have an Authorization header, and its associated identity will be used to authorize the request.

The response is created from the generate TOTP shared secret extended result, and its body is a JSON object with the following fields:

• resultCode

  A mandatory JSON object that contains the following fields:

  • value — The integer value for the LDAP result code. This is required.

  • name — A name for the LDAP result code. This is optional but recommended.

• diagnosticMessage

  An optional string field that holds a human-readable message with additional information about the operation.

• totpSharedSecret

  An optional string field that holds the base32-encoded representation of the TOTP shared secret that was generated by the server. This is present if the generate TOTP shared secret operation completed successfully, and absent if the operation failed.

The Get Password Quality Requirements extended operation is applicable for user-facing applications that allow users to create accounts or change passwords. This operation enables applications to display a list of the requirements that the new password must satisfy at the initial password request.

The Get Password Quality Requirements extended operation is not a standard LDAP operation and has been developed internally for use within PingDirectory products. Its implementation in the Directory REST API is based on the following classes in the UnboundID LDAP SDK:

• GetPasswordQualityRequirementsExtendedRequest

• GetPasswordQualityRequirementsExtendedResult

• GetPasswordQualityRequirementsExtendedOperation

The API method exists to serves as a translation layer between the client's HTTP request and Directory's internal LDAP operations. For more information on the LDAP Get Password Quality Requirements extended operation, see the LDAP GetPasswordQualityRequirementsExtendedRequest documentation. The LDAP get password quality requirements extended request has an OID of "1.3.6.1.4.1.30221.2.6.43".

The Password Modify extended operation for the Directory REST API is primarily based on the existing PasswordModifyExtendedRequest and the PasswordModifyExtendedResult in the UnboundID LDAP SDK. The API method serves as a translation layer between the client's HTTP request and Directory's internal LDAP operations. For the standard LDAP password modify extended operation specification, see RFC 3062.

The register YubiKey OTP device extended request, which is heavily based on the RegisterYubiKeyOTPDeviceExtendedRequest class in the LDAP SDK, causes the server to associate a YubiKey device with a user account so it can be used to authenticate that user.

The request body is a JSON object with the following fields:

• staticPassword

  An optional string field whose value is the static password for the user. If this is provided, then the POST request will not require an Authorization header, as the request will be authorized as the end user. If this is absent, then the request must have an Authorization header, and its associated identity will be used to authorize the request.

• otp

  A mandatory string field whose value is a one-time password generated by the YubiKey device to be registered with the user's account.

The response body is a JSON object with the following fields:

• resultCode

  A mandatory JSON object that contains the following fields:

  • value — The integer value for the LDAP result code. This is required.

  • name — A name for the LDAP result code. This is optional but recommended.

• diagnosticMessage

  An optional string field that holds a human-readable message with additional information about the operation.

The revoke TOTP shared secret extended operation can be used to revoke one or more shared secrets for a user so that time-based one-time passwords (TOTP) generated with those secrets can no longer be used to authenticate.

The request body is a JSON object with the following fields:

• staticPassword

  An optional string field whose value is the static password for the user. If this is provided, then the POST request will not require an Authorization header, as the request will be authorized as the end user. If this is absent, then the request must have an Authorization header, and its associated identity will be used to authorize the request.

• totpSharedSecret

  An optional string field whose value should be the base32-encoded representation of the TOTP shared secret to revoke. If this is absent, then all of the user's TOTP shared secrets will be revoked.

The response body is a JSON object with the following fields:

• resultCode

  A mandatory JSON object that contains the following fields:

  • value — The integer value for the LDAP result code. This is required.

  • name — A name for the LDAP result code. This is optional but recommended.

• diagnosticMessage

  An optional string field that holds a human-readable message with additional information about the operation.