2.7.1.2 Search for a Directory Object - Client Application

  • Article

In this use case, an administrator or user wants to inspect the attribute values for a given set of directory objects in order to make informed decisions about the Active Directory system. To achieve this task, the administrator or user launches the client application to interact with the Active Directory system. The client application establishes a connection to the Active Directory system. The administrator or user then performs a search on the directory tree.

Goal

Retrieve information from one or more directory objects in the Active Directory system.

Context of Use

An administrator or user wants to search for and retrieve the attribute values of the existing directory object.

Use case diagram for searching for a directory object

Figure 8: Use case diagram for searching for a directory object

Actors

  • Client application

    The client application is the primary actor. It is the entity that prepares the connection to the directory server, submits search requests to the directory on behalf of the user, and returns the results to the user.

  • Windows Authentication Services

    Windows Authentication Services [MS-AUTHSOD] is the supporting actor that authenticates the administrator's or user's identity. This is done so that access control decisions can be made by the Active Directory system.

  • Directory server

    The directory server is the supporting actor that receives the search request and performs the search of the application directory.

Stakeholders

  • Administrator or user

    The administrator or user is the entity that initiates the search in the application directory. The administrator or user primarily wants to obtain the search results.

  • Directory

    The application directory is the directory that contains the application-specific directory objects.

    In this operation, the directory remains unchanged.

Preconditions

  • The system-wide preconditions, as described in section 2.6, are satisfied. The Active Directory system completes initialization, as described in section 2.6.

  • The client application has access to a directory server to which it can establish a connection, if it is not already connected, and send the request.

Main Success Scenario

  1. Trigger: To initiate a search, the administrator or user provides the search criteria for the directory objects that are of interest as input to the client application, along with credentials. The administrator or user then invokes the operation that searches for directory objects. The search criteria also specify what information about each object is to be returned.

  2. The client application establishes a connection to the directory server. Windows Authentication Services authenticates the client application by using the supplied credentials ([MS-AUTHSOD] section 2).

  3. The client application sends a request to the directory server to search for the directory objects, specifying the search criteria.

  4. The directory server verifies that the credentials that are supplied through the client application have the necessary access-control rights to complete the operation ([MS-ADTS] section 5.1.3).

  5. The directory server identifies all directory objects that match the criteria that the client application supplies. From the set of directory objects that is identified, the directory server extracts the information that the client application requests.

  6. The directory server sends a response to the client application that contains the extracted information.

Postcondition

Information for the directory object is available to the client application.

Extensions

  • If the search criteria that the client application supplies returns a result set that is larger than the configured MaxPageSize ([MS-ADTS] section 3.1.1.3.4.6):

    1-5. Same as Main Success Scenario.

    6. The directory server sends a response to the client application that it has exceeded the size limit for the request and returns all results up to the limit for the result size.

  • If the search criteria that the client application supplies potentially return objects that are located on a different NC:

    1-4. Same as Main Success Scenario.

    5. Because the directory server that the client application is connected to does not host the objects that the search criteria specify, the directory server determines that another server or NC is better suited to process the search request ([MS-ADTS] section 3.1.1.4.6).

    6. The directory server sends a response to the client application that a referral error has occurred.