How to poll for object attribute changes in Active Directory on Windows 2000 and Windows Server 2003

You can use the following two polling methods to monitor changes in Active Directory:

• Use the Active Directory directory synchronization (DirSync) control.
• Use Update Sequence Number (USN) queries that use the uSNChanged attribute.

Method 1: The DirSync control

The DirSync control is a Lightweight Directory Access Protocol (LDAP) server extension that enables a program to search an Active Directory partition for objects that have changed. When a program performs a DirSync search, the program creates a cookie that identifies the directory state at the time of an earlier DirSync query. With the first search, the program creates an empty cookie and Active Directory returns all objects that satisfy the query. Active Directory also returns an updated cookie that can be passed to the next search to obtain changes that are made since the first search. This process is repeated for each search.

DirSync control behavior and limitations

The DirSync control searches are performed against the whole Active Directory partition or naming context. By default, Active Directory domain controllers host the following three partitions:

• Domain container
• Configuration container
• Schema container

A DirSync control search returns all the changes that are made to an Active Directory object regardless of the permissions that are set on the object. Additionally, a DirSync control search that is run with the appropriate permissions returns deleted objects. Deleted objects are also known as tombstones.

Although the DirSync control is powerful and efficient, it has two limitations. The first limitation is that the control must run by using a user account that has the Replicating Directory Changes permission on the domain naming context. By default, the Administrator user account has this permission. However, we do not recommend that you use the Administrator account to run your DirSync control program. Instead, we recommend that the Replicating Directory Changes permission be granted to a typical user account or group. Therefore, you can configure permissions that are specific and limited to the DirSync control program.

To grant the Replicating Directory Changes permission, you must modify the permissions on the directory partition object.
For additional information about how to grant the Replicating Directory Changes permission, click the following article number to view the article in the Microsoft Knowledge Base:

303972 How to Grant the "Replicating Directory Changes" Permission for the Microsoft Metadirectory Services ADMA Service Account

The second DirSync control limitation is that the DirSync control search cannot be confined to a specific area of Active Directory. Because all changes made to an Active Directory partition are returned from a DirSync control search, access to object data that is not wanted may occur.

Microsoft Windows 2000 and the DirSync control

Microsoft Windows 2000 Active Directory supports only one mode when you use the DirSync control. This mode is named Per Partition and has the following characteristics:

• All changes to Active Directory objects are returned regardless of the permissions on those objects.
• Deletions are returned as tombstone objects. This makes it possible for programs to track deletions.
• Only the Replicating Directory Changes permission on the Active Directory partition is required.

Microsoft Windows Server 2003 and the DirSync control

By default, Microsoft Windows Server 2003 Active Directory supports Per Partition mode. Additionally, Windows Server 2003 supports another mode that is named Per Object mode.

You can specify Per Object mode when you develop a program by using a flag that is passed in to the LDAP search function. If your program specifies the Per Object mode, the Replicating Directory Changes permission is not required.

Note An Active Directory administrator cannot specify whether a program can use Per Partition mode or Per Object mode. The mode is determined by the LDAP search function that is coded in the program.

Method 2: USN queries using the uSNChanged attribute

When a domain controller modifies an object, it increments the highestCommittedUSN attribute value. When the increment occurs, the domain controller also sets the uSNChanged attribute for that object to the new value. In this process, each change to an object in Active Directory is stamped with a unique and monotonic value. Therefore, a program can obtain the most recent changes to an object on a domain controller by finding the object that has the largest uSNChanged attribute value. Similarly, the second largest uSNChanged attribute value corresponds to the second most recently changed object, and this process is repeated.

Monitoring USN changes behavior

The uSNChanged attribute is not replicated. Therefore, when you read a uSNChanged attribute for an object on two different domain controllers, the uSNChanged attribute typically returns values that are different.


To maintain consistency by using the uSNChanged attribute, a program must first perform a full synchronization with Active Directory, and then determine the highest uSNChanged attribute value for the objects that are returned. When the program polls for changes, it can search Active Directory for all objects whose uSNChanged attribute value is larger than the value that was read earlier.

Monitoring USN changes benefits and permissions

There are two benefits with using the uSNChanged attribute to poll for Active Directory object changes. The first benefit is that an uSNChanged attribute value search can be confined to a specific area of Active Directory. For example, unlike the DirSync control, object change searches can be limited to a specific subtree in the directory.

The second benefit is that you do not have to configure special user account permissions or group permissions for the program. The program only requires List and Read permissions for every container and leaf object in the subtree that is searched.

Note If you use the DirSync control method, you must configure the user account or group that has Read Property and List permissions on the Deleted Objects container to return Active Directory objects that have been deleted.

If your program does not have permissions to access an object, object data is not returned by the program. Additionally, the uSNChanged attribute is stored by using a per-object method, instead of a per-attribute method. Because of this, all attributes that are associated with the object are returned instead of only modified attributes.

Whether you use the DirSync control method or the USN change method, programs that search Active Directory only return the objects and attributes where they have the appropriate permissions. For example, objects that are in the Deleted Objects container, may not be returned in the search. For example, a tombstones is an object that might be in the Deleted Objects container. By default, the Deleted Objects container can only be accessed by the System and Administrator accounts.

Object deletion detection

To detect object deletions, a program must either perform a periodic full synchronization of Active Directory, or it must separately search the Deleted Objects container and remove from its own database the objects that have been deleted in Active Directory.

For more information about tracking changes in Active Directory, visit the following Microsoft Web site: For more information about polling for changes using the DirSync control, visit the following Microsoft Web site: For more information about polling for changes using the uSNChanged attribute, visit the following Microsoft Web site: For more information about polling Active Directory for changes, view the help information that is included with the Microsoft Platform Software Development Kit (SDK).