LDAP: Operation Purpose Request Control

UnboundID’s Directory Server Suite 3.2 supports a new request control, the Operation Purpose Request Control. The Operation Purpose Request Control includes the following pieces of data:

  • application name
  • application version
  • code location
  • request purpose

Applications can use this request control to indicate the purpose of the request to the directory server. The directory server can log this information, and client connection policies can allow or disallow any request control, including this one. This request control could serve as an aid to security auditing as well as application debugging. The code location is a number indicating how many stack frames to include in the request control (a value of less than equal to zero means all stack frames).


A request control is a piece of data attached to an LDAP request. Before using a request control, an application must check the root DSE to ensure that the server supports the request control, otherwise, the server may reject the request.

Example: Use Java to search and attach an operation purpose request control

SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
        SearchScope.SUB, Filter.createEqualityFilter("uid", uidValue),
searchRequest.addControl(new OperationPurposeRequestControl(appName,
        appVersion, 0,  "Retrieve the entry for a user with a given uid");
Entry userEntry = connection.searchForEntry(searchRequest);
SimpleBindRequest bindRequest = nwe SimpleBindRequest(userEntry.getDN(),
        password, new OperationPurposeRequestControl(appName, appVersion, 0,
        "Bind as a user to verify the provided credentials."));
BindResult bindResult = connection.bind(bindRequest);

The server’s access log after the search

After running the search, the application name and application version will appear in the directory server logs. Additionally, the location of the code and the stated purpose appear in the log:

[30/Oct/2011:06:05:42.295 -0400] SEARCH RESULT 
 opPurpose="app='Operation Purpose Request Control Demonstration'
 purpose='Demonstrate the use of the operation purpose request control'"

The individual portions of the access log entry are split, one per line, to better illustrate the results of issuing the search request with an operation purpose request control attached. The following table explains the elements of the log entry:

instanceName The configured name of the directory server instance
conn The LDAP connection number (for information about the protocol, see LDAP: The Protocol)
op The LDAP operation number
msgID The LDAP message ID number
requesterIP The IP address of the client which issued the request
requesterDN The distinguished name of the authentication state of the connection
requestControls The OID of the request controls attached to the connection
opPurpose The purpose of the operation (from the operation purpose request control)
version The application version (from the operation purpose request control)
purpose The application purpose (from the operation purpose request control)
base The base object of the search request
scope The scope of the search request
filter Filters search results, that is, determines which entries are returned to the client
attrs The list of requested attributes
resultCode The result code, in this case, “success”
etime The elapsed time taken to process the search request, in this case .969 milliseconds
entriesReturned The number of entries which matched the filter and were returned to the client


About Terry Gardner

Terry Gardner was a leading directory services architect with experience with many large scale directory services installations and messaging server installations, and was a Subject Matter Expert in the field of Directory Services and Solaris (operating system) performance. Mr. Gardner also participated in the open-source software community. Mr. Gardner passed away in December, 2013.
This entry was posted in computing, Java, LDAP and tagged , , , , , , , . Bookmark the permalink.

2 Responses to LDAP: Operation Purpose Request Control

  1. Pingback: LDAP: Status of User Accounts in a Directory Server Database « Diaries, Triumphs, Failures, and Rants

  2. Pingback: LDAP: Using Java to bind to a directory server « Diaries, Triumphs, Failures, and Rants

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s