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.