3.2.9 Example 9: Obtain a List of User Accounts Using the Web Services Protocols

One way to obtain a list of users in the Active Directory system is to use the Web Services protocols, specifically WS-Enumeration [WSENUM], to query the directory. A client application can create a query with a supplied filter to locate accounts that are based on specific criteria, similar to an LDAP search operation.

To perform this task, the client application uses the Web Services protocols to send a query to the directory service. This example uses the WS-Enumeration protocol to communicate with the directory service.

This example covers the use case in section 2.7.1.2, Search for Directory Object - Client Application.

Prerequisites

The general requirements described in section 2.6, Assumptions and Preconditions.

The Active Directory system meets all preconditions described in section 2.7.1.2.

Initial System State

The system supports the Web Services protocols (see section 2.8).

Final System State

The requested information for the user object(s) is returned to the client application.

Sequence of Events

The following sequence diagram shows the message flow that is associated with this example.

Figure 54: Communication flow for obtaining a list of user accounts by using the Web Services protocols

The client application uses the net.tcp transport to establish a connection to the directory service. In this example, all communications that are sent and received via this transport use the SOAP 1.2 and [WSAddressing] (WS-Addressing) protocols. Unless otherwise noted, all responses that include a return code contain a return code that indicates that the operation was successfully performed.

1. The client application sends a SOAP message that contains a WS-Enumeration Enumerate request ([WSENUM] section 3.1). The filter section of the Enumerate request contains the query that the client intends to use to identify which accounts are to be returned ([MS-WSDS] section 3.1.4.1.1.1). The filter also includes (objectClass=user) to indicate that only user directory objects are to be returned.

   The request also contains a Selection element that indicates which attributes of the queried user objects are to be returned to the client ([MS-WSDS] section 3.1.4.1.1.2).

2. The directory server processes the request and generates an enumeration context ([WSENUM] section 3) that the client application can use in further requests. It then returns a SOAP message that contains a WS-Enumeration Enumeration response with the enumeration context and the expiration time of the request.

3. Now that the client application has set up the enumeration, it can begin to request data. It sends a SOAP message that contains a Pull request ([WSENUM] section 3.2). The request contains the previously returned enumeration context along with optional values such as the number of items (directory objects) that the server is to return to the client application in the Pull response.

4. The server retrieves the matching user objects ([MS-ADTS] section 3.1.1.3.1.3) from the directory. It returns a SOAP message that contains a Pull response to the client application ([WSENUM] section 3.2). This response contains the objects that match the client application's query, including the attributes of those objects that the client requested in the Enumerate request that established the enumeration context.

   The client application repeats sending Pull requests and processing Pull responses as needed until the directory service indicates that there is no additional data to retrieve ([WSENUM] section 3.2).

5. When all the data that was requested is retrieved, the client application terminates the enumeration by sending a SOAP message that contains a Release request ([WSENUM] section 3.5). This tells the server that the client application is finished with the enumeration content and that the server can release any server-side resources that it has allocated to process the enumeration.

   Note If the wsen:EndOfSequence element is obtained by the client in the Pull response, then the Release request is not sent.

6. The server performs any necessary processing of the Release request and returns a Release response to the client.