Windows-based Hosting::CreateUser

  • Article

The CreateUser procedure creates a new user within a specified organization according to the policy name passed in as <policyName>. Possible values for this tag are "hosting," "reseller," "customer," and "default." The default policy creates only the requested organization. The exact behaviors of these policies are defined in the GetPolicy procedure in the Managed Active Directory namespace.

Arguments

The CreateUser procedure has the following input parameters.

Input Argument Description

<container>

A valid Lightweight Directory Access Protocol (LDAP) path of the OU where the new user will be created. For example: LDAP://OU=alpineskihouse,OU=Reseller1,OU=Hosting,DC=fabrikam,DC=Com.

<userPrincipalName>

The user principal name (UPN) of the user. Typically this will be <user>@<SMTPDomain> to enable a UPN login to the e-mail account with the user's e-mail address.

Dd278784.note(en-us,TechNet.10).gifNote
You cannot use the <userPrincipalName> parameter to create the HostingAdmin user in the OU=Hosting container as follows: <userPrincipalName>HostingAdmin@Hosting</userPrincipalName>. However, you can create the HostingAdmin user with the CreateUser procedure of the Managed Active Directory Namespace (or ASP.NET Web Service) by using <policyName>Hosting</policyName> and then calling the GroupAdd procedure to add the user to the Admins group in the Hosting container.

<preferredDomainController>

The name of the preferred domain controller.

<isAdmin>

Include and set this element to "1" if you want the new user to be an administrator of the organization. Do not include this tag if you do not want the user to have administrative privileges.

<newPassword>/@do-not-log=1

The user's password.

<sAMAccountName>

The SAM account name.

<policyName>

The policy name (defaults to "default").

<giveName>

The given name, surname, middle name, and initials.

<displayName>

The display name.

<description>

A description of the user account.

<properties>

Any valid Active Directory properties for object class user.

Output Arguments

The CreateUser procedure returns the <user> tag containing the user object created and the membership and security policies supplied. Each object created has its LDAP path in a "path" attribute.

Remarks

sAMAccountName Behavior

When creating a user, it is necessary to also ensure that the new user's sAMAccountName is unique within the domain. If it is not, the CreateUser procedure will fail. Also, interactions with Exchange make it undesirable for the '@' character to appear in a sAMAccountName. Therefore, when creating or renaming a user or group, the sAMAccountName will be similar to the input name (or Universal principal name), except that illegal sAMAccountName characters are removed, and '@' characters are replaced with '_'. If the sAMAccountName collides with an existing sAMAccountName, then a random string of digits will be appended to the sAMAccountName to ensure uniqueness.

The algorithm for generating a sAMAccountName from the seed name (Universal Principal Name for a user, or CN if the object is a group), is as follows:

  • Remove all of the following illegal characters from the seed name: "/\[]:|<>+=;?,*.

  • Trim the seed name to a maximum of 20 characters.

  • If the last character is a '.', replace it with '_'.

  • Attempt to create the object with the trial sAMAccountName.

  • If there is a sAMAccountName collision in step 4, generate 3 trial names by limiting the seed name to 17 characters, then append a random 3-digit number to each. Generate 2 additional trial names by limiting the seed name to 15 characters, then append a 5-digit random number to each. Attempt to create the object using each of these 5 trial names in turn.

Security

The CreateUser procedure has the following security requirements:

  • The caller is impersonated.

  • The caller is tested for OrgCreator permissions.

Policy Information

The CreateUser procedure retrieves policy information using the GetPolicy procedure of the Managed Active Directory Namespace.

Process Steps

The following steps occur when creating a user with the CreateUser procedure of the Managed Windows-based Hosting Namespace:

  • Create either a reseller or a customer user.

  • Create the user in Active Directory by calling the Active Directory Provider::CreateBusinessUser.

  • Enable the user.

  • Set the user's password.

  • Apply the creation, membership, and security policies defined in the GetPolicy procedure of the Managed Active Directory Namespace.

  • Add the user to the Customer Service Plans database.

Sample Code

Example XML Request

The following is an example of an XML request for the CreateUser procedure of the Managed Windows-based Hosting Namespace:

<request> 
        <data/> 
                <procedure> 
                        <execute namespace="Windows-based Hosting" procedure="CreateUser" 
                        impersonate="1"> 
                                <executeData> 
              <container>LDAP://OU=Reseller1,OU=Hosting,DC=raven, 
                                        DC=com</container> 
                                        <userPrincipalName>upnMyUser1</userPrincipalName> 
                                        <sAMAccountName>jwalsh</sAMAccountName> 
                                        <policyName>reseller</policyName> 
                                        <displayName>Joe Walsh</displayName> 
                                        <givenName>Joe</givenName> 
                                        <middleName>Guitarist</middleName> 
                                        <sn>Walsh</sn> 
                                        <initials>JW</initials> 
                                        <description>User description</description> 
                                        <properties> 
                                                <property name="otherHomePhone"> 
                                                        <value>425-555-1212</value> 
                                                        <value>206-555-1212</value> 
                                                </property> 
                                        </properties> 
                                        <preferredDomainController>myPrimaryDC.raven.com 
                                        </preferredDomainController> 
                                        <newPassword do-not-log="1">NewPassWord1</newPassword> 
                                </executeData> 
                                <after source="executeData" destination="data"  
                                sourcePath="user"/> 
                        </execute> 
                </procedure> 
</request>

Example XML Response

The following is an example of an XML response from the CreateUser procedure of the Managed Windows-based Hosting Namespace:

<response> 
        <data> 
                <user path="LDAP://cn=upnMyUser1,OU=Reseller1,OU=Hosting, 
                DC=raven,DC=com" name="upnMyUser1"samName="upnMyUser1"></user> 
        </data> 
</response>

Applies To

Managed Windows-based Hosting Namespace API for:

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

Windows-based Hosting::DeleteUser