Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
A common administrative task is to provision an account for a new user. As shown in the previous section, this can be done by using LDAP. Another way to accomplish this task is to use the SAMR protocol to communicate with the Active Directory system. Regardless of which protocol is chosen, the end state is the same: a new user object is created in the directory tree.
To perform this task, an administrator runs a client application, using the SAMR protocol from a client computer that targets a directory server in the Active Directory system.
This example applies only to AD DS.
This example differs from the previous example (section 3.2.1) in that it uses the SAMR protocol rather than LDAP to create the user and in that it only provides a minimal set of attributes for the newly created account.
This example covers the use case in section 2.7.2.1, Create a New Account - Client Application.
Prerequisites
The general requirements described in section 2.6, Assumptions and Preconditions.
The Active Directory system meets all preconditions described in sections 2.7.1.1 and 2.7.2.1.
Initial System State
None.
Final System State
The new user object has been created in the directory.
Sequence of Events
The following sequence diagram depicts the message flow that is associated with this example.
Figure 47: Message flow for provisioning a user account by using the SAMR protocol
Unless otherwise noted, all responses that include a return code contain a return code that indicates that the operation was successfully performed.
The client binds to the SAMR endpoint on the server using a supported transport, as specified in [MS-SAMR] section 2.1.
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) with the DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1) to the server, requesting a server handle.
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 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 in steps 4-7.
The client application sends a SamrEnumerateDomainsInSamServer request ([MS-SAMR] section 3.1.5.2.1), using the server handle that it previously obtained in step 3.
The server processes the request ([MS-SAMR] section 3.1.5.2.1) and returns a list of all domains hosted by the server.
The client application repeats sending a SamrEnumerateDomainsInSamServer request if the directory service returns STATUS_MORE_ENTRIES ([MS-SAMR] section 3.1.5.2.1) to indicate that there is additional data to retrieve.
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 one of the names that was returned in step 5, which corresponds to the domain object.
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.
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 DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1).
The server processes this request ([MS-SAMR] section 3.1.5.1.5) and returns a response with a domain handle.
Now that the client application has the domain handle, it can use this handle to create users in the domain.
The client application sends a SamrCreateUser2InDomain request ([MS-SAMR] section 3.1.5.4.4) with the DesiredAccess parameter set to MAXIMUM_ALLOWED ([MS-SAMR] section 2.2.1.1) to create the new user. The request includes the domain handle that was received earlier and the user name of the new user to create. It has the AccountType parameter set to USER_NORMAL_ACCOUNT ([MS-SAMR] section 2.2.1.12). The request also specifies the account type (in this case USER_NORMAL_ACCOUNT) and the desired access on the returned user handle (in this case USER_WRITE_ACCOUNT and USER_FORCE_PASSWORD_CHANGE so that the account can be updated in subsequent steps).
The server processes the request ([MS-SAMR] section 3.1.5.4.4) and creates the new user. It creates a user directory object with sAMAccountName set to the user name that the client application specified in the request. The server then returns a response with a user handle for the newly created user, the relative identifier (RID) of the new user, and the access that was granted on the user handle (in accordance with the behavior specified in [MS-SAMR] section 3.1.5.4.4).
The client application sends a SamrQueryInformationUser request ([MS-SAMR] section 3.1.5.5.6), using the user handle it obtained in the previous step, and requesting that UserControlInformation be returned. This is done in order to retrieve the value of the userAccountControl attribute of the newly created user.
The server processes the request ([MS-SAMR] section 3.1.5.5.6), and returns the value of the userAccountControl attribute (in accordance with the behavior specified in [MS-SAMR] sections 3.1.5.4.4 and 3.1.5.14.11) of the newly created user.
To obtain password policy information, the client application sends a SamrGetUserDomainPasswordInformation request ([MS-SAMR] section 3.1.5.13.3), using the user handle that it previously obtained in step 11 for the newly created user.
The server processes the request ([MS-SAMR] section 3.1.5.13.3) and returns information about the password policy that applies to the newly created user.
The client application sets the password of the newly created user by sending a SamrSetInformationUser2 request ([MS-SAMR] section 3.1.5.6.4) that specifies a UserInformationClass of UserInternal4InformationNew. As part of this request, it also updates the value of the user's userAccountControl attribute (whose current value was previously retrieved in steps 12 and 13) with any additional bits ([MS-SAMR] section 2.2.6.1) based on values that the administrator provided.
The server processes the request ([MS-SAMR] section 3.1.5.6.4) and returns a response that indicates that the user was successfully updated.
- 20. 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 is attempting to close. The client application closes the handles in the reverse order that they were received (namely, the user handle, the domain handle, and then the server handle).
As the final step, the transports that were created for communication are closed.