3.2.7 Example 7: Determine the Group Membership of a User

  • Article

In this example, an administrator queries the directory to determine the group membership of a user. The administrator does so by using the SAMR protocol. To perform this task, an administrator runs a client application from a client computer that targets a directory server in the Active Directory system. The client application uses the SAMR protocol to query the user's group membership.

This example applies only to AD DS.

This example uses the SAMR protocol.

This example covers the use case in section 2.7.2.7, Query an Account's Group Membership - 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.2.7.

Initial System State

None.

Final System State

The user's group membership information has been returned to the client application.

Sequence of Events

The following sequence diagram depicts the message flow associated with this example.

Message flow for determining the group membership of a user

Figure 52: Message flow for determining the group membership of a user

Unless otherwise noted, all responses that include a return code contain a return code that indicates that the operation was performed successfully.

  1. The client application uses a supported transport to bind to the SAMR endpoint on the server, as specified in [MS-SAMR] section 2.1.

  2. The next step is to open a SAMR handle to the directory server. To obtain a server handle, the client application sends a SamrConnect5 request ([MS-SAMR] section 3.1.5.1.1) with the DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1) to the directory server.

  3. The server processes the request ([MS-SAMR] section 3.1.5.1.1) and sends a response with the server handle to be used by later calls.

    Before the client application continues to open a SAMR handle to the domain, the client has to first know the SID of the domain. This is determined in steps 4 and 5.

  4. The client application sends a SamrLookupDomainInSamServer request ([MS-SAMR] section 3.1.5.11.1), using the server handle from step 3. In this request, it specifies the domain name for the account.

  5. The server processes the request ([MS-SAMR] section 3.1.5.11.1) and returns the domain SID.

    The client application has now obtained the domain SID and can use it to open a SAMR handle to the domain.

  6. The client application sends a SamrOpenDomain request ([MS-SAMR] section 3.1.5.1.5), using the server handle that it previously obtained in step 3 and the domain SID that it obtained in step 5, with the DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1).

  7. The server processes this request ([MS-SAMR] section 3.1.5.1.5) and returns a response with a domain handle.

    The client application now obtains the relative identifier (RID) of the user so that it can open a user handle.

  8. The client application sends a SamrLookupNamesInDomain request ([MS-SAMR] section 3.1.5.11.2). The request includes the user name and the domain handle.

  9. The server processes the request ([MS-SAMR] section 3.1.5.11.2) and returns the RID of the user account.

    The client application now has the user account RID and can use it to open a handle to the user.

  10. The client application sends a SamrOpenUser request ([MS-SAMR] section 3.1.5.1.9) with the DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1). The request includes the domain handle and the RID of the user.

  11. The server processes the request ([MS-SAMR] section 3.1.5.1.9) and returns a response with a user handle.

  12. Now that the client application has a handle to the user, it calls SamrGetGroupsForUser ([MS-SAMR] section 3.1.5.9.1) to retrieve the group membership of the user.

  13. The server processes the request ([MS-SAMR] section 3.1.5.9.1) and returns a response with the list of groups that the user is a member of.

  14. -  16. The client application performs cleanup by closing all the handles that it opened during the session. This is done by calling SamrCloseHandle ([MS-SAMR] section 3.1.5.13.1) with SamHandle set to the handle that the client application is attempting to close. The client application closes the handles in the reverse order in which they were received (that is, the user handle, the domain handle, and then the server handle).