Share via

3.2.4 Example 4: Change a User Account's Password

  • Article

In this example, a user changes the password on their account by using the SAMR protocol. To perform this task, a user 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 change the account's password.

This example applies only to AD DS.

This example uses the SAMR protocol.

This example covers the use case in section 2.7.2.3, Change an Existing Account's Password (PDC) - 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.3.

Initial System State

None.

Final System State

The user account's password in the directory has been changed to the new value.

Sequence of Events

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

Message flow for changing a user account's password

Figure 49: Message flow for changing 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 binds to the SAMR endpoint on the server using a supported transport, as specified in [MS-SAMR] section 2.1.

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

  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 in later calls.

    Before continuing by opening a SAMR handle to the domain, the client application has to first know the domain names hosted by the directory server. This is determined by using steps 4 and 5.

  4. The client application sends a SamrEnumerateDomainsInSamServer request ([MS-SAMR] section 3.1.5.2.1), using the server handle from step 3.

  5. The server processes the request ([MS-SAMR] section 3.1.5.2.1) and returns a SAMPR_ENUMERATION_BUFFER array containing the domain information hosted by the directory server.

    Before continuing by opening a SAMR handle to the domain, the client application has to first know the security identifier (SID) of the domain. This is determined by using steps 6 and 7.

  6. The client application sends a SamrLookupDomainInSamServer request ([MS-SAMR] section 3.1.5.11.1), using the server handle from step 3 for each directory server domain name returned in step 5 until it finds a domain that is not the Builtin domain (S-1-5-32).

  7. 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.

  8. 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 7, with the desired value set in the DesiredAccess parameter ([MS-SAMR] section 2.2.1.1).

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

  10. 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 Builtin domain SID, with the desired value set in the DesiredAccess parameter ([MS-SAMR] section 2.2.1.1).

  11. 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.

  12. The client application sends a SamrLookupNamesInDomain request ([MS-SAMR] section 3.1.5.11.2) to ensure that the user exists. The request includes the domain handle and the sAMAccountName attribute.

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

  14. 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.

  15. 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.

  16. 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).

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

  18. The client application sends a SamrQueryInformationUser request ([MS-SAMR] section 3.1.5.5.6) to the server to query all user information.

  19. The server processes the request and returns a response with all user information.

  20. The client application sends a SamrQuerySecurityObject ([MS-SAMR] section 3.1.5.12.2.1) request to the server to obtain the security descriptor for the user object in the directory server.

  21. The server processes the request ([MS-SAMR] section 3.1.5.12.2.1) and returns a response with the security descriptor set on the user object in the directory server.

  22. The client application sends a SamrGetUserDomainPasswordInformation request ([MS-SAMR] section 3.1.5.13.3) to the server to query for the password policy applied on the user in the domain.

  23. The server processes the request ([MS-SAMR] section 3.1.5.13.3) and returns a response with domain password information about the user to the application.

  24. Now that the client application has a handle to the user, it calls SamrSetInformationUser2 to change the user's password. The server processes the request, returns STATUS_SUCESS, and changes the password of the user. Refer to [MS-SAMR] section 3.1.5.6.4.

  25. -  28. 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 handles, and then the server handle).