Active Directory Cookbook

4.3. Using LDAP Controls

Problem

You want to use an LDAP control as part of an LDAP operation.

Solution

Using a graphical user interface

1. Open LDP.

2. From the menu, select Options → Controls.

3. For the Windows Server 2003 version of LDP, select the control you want to use under Load Predefined. The control should automatically be added to the list of Active Controls.

   For the Windows 2000 version of LDP, you’ll need to type the object identifier (OID) of the control under Object Identifier.

4. Enter the value for the control under Value.

5. Select whether the control is server- or client-side under Control Type.

6. Check the box beside Critical if the control is critical.

7. Click the Check-in button.

8. Click OK.

9. At this point, you will need to invoke the LDAP operation (for example, Search) that will use the control. In the dialog box for any operation, be sure that the “Extended” option is checked before initiating the operation.

Using VBScript

None of the ADSI automation interfaces directly expose LDAP controls. That means they cannot be utilized from VBScript. On the other hand, many of the controls, such as paged searching or deleting a subtree, are wrapped within their own ADSI methods that can be used within VBScript.

Any LDAP-based API, such as the Perl Net::LDAP modules, can be used to set controls as part of LDAP operations.

Discussion

LDAP controls were defined in the LDAPv3 specification as a way to extend LDAP and its operations without breaking the protocol. Many controls have been implemented, some of which are used when searching the directory (e.g., paged searching, VLV, finding deleted objects, and attribute scoped query), and some are needed to do certain modifications to the directory (e.g., cross-domain object moves, tree delete, and permissive modify). Controls can be marked as critical, which means they must be processed with the request, or an error is returned. If an unsupported control is not flagged as critical, the server can continue to process the request and ignore the control.

The complete list of controls supported by Active Directory is included in Table 4-2.

Table 4-2. LDAP controls supported by Active Directory

Name	OID	Description
Paged Results	1.2.840.113556.1.4.319	Instructs the server to return search results in “pages.”
Cross Domain Move	1.2.840.113556.1.4.521	Used to move objects between domains.
DIRSYNC	1.2.840.113556.1.4.841	Used to find objects that have changed over a period of time.
Domain Scope	1.2.840.113556.1.4.1339	Informs the server to not generate any referrals in a search response.
Extended DN	1.2.840.113556.1.4.529	Used to return an object’s GUID and SID (for security principals) as part of its distinguished name.
Lazy Commit	1.2.840.113556.1.4.619	Informs the server to return after directory modifications have been written to memory, but before they have been written to disk. This can speed up processing of a lot of modifications.
Change Notification	1.2.840.113556.1.4.528	Used by clients to register for notification of when changes occur in the directory.
Permissive Modify	1.2.840.113556.1.4.1413	Allows duplicate adds of the same value for an attribute or deletion of an attribute that has no values to succeed (normally, it would fail in that situation).
SD Flags	1.2.840.113556.1.4.801	Used to pass flags to the server to control certain security descriptor options.
Search Options	1.2.840.113556.1.4.1340	Used to pass flags to the server to control search options.
Show Deleted Objects	1.2.840.113556.1.4.417	Used to inform the server to return any deleted objects that matched the search criteria.
Server-side Sort Request	1.2.840.113556.1.4.473	Used to inform the server to sort the results of a search.
Server-side Sort Response	1.2.840.113556.1.4.474	Returned by the server in response to a sort request.
Tree Delete	1.2.840.113556.1.4.805	Used to delete portions of the directory tree, including any child objects.
Verify Name	1.2.840.113556.1.4.1338	Used to target a specific GC server that is used to verify DN-valued attributes that are processed during add or modification operations.
VLV Request	2.16.840.1.113730.3.4.9	Used to request a virtual list view of results from a search. This control is new to Windows Server 2003.
VLV Response	2.16.840.1.113730.3.4.10	Response from server returning a virtual list view of results from a search. This control is new to Windows Server 2003.
Attribute Scoped Query	1.2.840.113556.1.4.1504	Used to force a query to be based on a specific DN-valued attribute. This control is new to Windows Server 2003. See Recipe 4.8 for an example.
Search Stats	1.2.840.113556.1.4.970	Used to return statistics about an LDAP query. See Recipe 15.9 for an example.
Incremental Multivalue Retrieval	1.2.840.113556.1.4.802	Retrieve a range of values for a multi-valued attribute instead of all values at once. This control is new to Windows Server 2003.

See Also

RFC 2251 (Lightweight Directory Access Protocol (v3)) for a description of LDAP controls, MSDN: Extended Controls, and MSDN : Using Controls