3.2.5 Example 5: Change a User Account's Password Against a Non-PDC DC

In this example, a user changes the password on the user account by using the SAMR protocol. To perform this task, a user runs a client application on a client computer that targets a DC in the Active Directory system. The client application uses the SAMR protocol to change the account's password.

In this example, the client connects to a DC that is not a primary domain controller (PDC) in order to change the account password. This example demonstrates the communication between a DC and a PDC when a user sends a password change request.

This example applies only to AD DS.

This example uses the SAMR, SAMS, and NRPC protocols.

This example covers the use case in section 2.7.2.4, "Change an Existing Account's Password (DC) - Client Application".

Prerequisites

The general requirements set forth in section 2.6, "Assumptions and Preconditions".

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

Initial System State

None.

Final System State

The user account's password in the DC has been changed to the new value, and it is also updated at the PDC.

Sequence of Events

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

Figure 50:  Message flow to change a user account's password

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 DC, as described in [MS-SAMR] section 2.1.

 2. The next step is to open a SAMR handle to the DC's SAMR server. The client application sends a SamrConnect5 request ([MS-SAMR] section 3.1.5.1.1) to the DC with the desired value set in the DesiredAccess parameter ([MS-SAMR] section 2.2.1.1). This message requests a server handle.

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

Before the client application can open a SAMR handle to the domain, it has to first have 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) that uses the server handle from step 3. In this request, it specifies the domain name for the account.

 5. The DC 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) that includes the server handle that it obtained in step 3 and the domain SID that it obtained in step 5 with the desired value set in the DesiredAccess parameter ([MS-SAMR] section 2.2.1.1).

 7. The DC 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 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 domain handle and the sAMAccountName attribute.

 9. DC 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). The request includes the domain handle and the RID of the user, and has the desired value set in the DesiredAccess parameter ([MS-SAMR] section 2.2.1.1).

11. The directory 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 SamrSetInformationUser2 to change the user's password. The DC changes the password of the user. Refer to [MS-SAMR] section 3.1.5.6.4.

13. – 20. The DC establishes a secure channel with the PDC, as specified in [MS-NRPC] section 3.1.4.1.

21. The DC sends a password update request to the PDC, as specified in [MS-SAMS] section 3.2.4.4, using the NetrLogonSendToSam method defined in [MS-NRPC] section 3.5.4.8.4, and according to the rules in [MS-NRPC] section 3.4.5.6.4.

22. The PDC processes the request according to the rules specified in [MS-SAMS] section 3.3.5.2 and [MS-NRPC] section 3.5.4.8.4, and returns a response.

23. The DC returns a response to the client application.

24. – 25. 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 created (that is, the user handle, the domain handle, and then the server handle).