JoinDomainOrWorkgroup method of the Win32_ComputerSystem class
The JoinDomainOrWorkgroup method joins a computer system to a domain or workgroup.
This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.
Syntax
uint32 JoinDomainOrWorkgroup(
[in] string Name,
[in] string Password,
[in] string UserName,
[in] string AccountOU,
[in] uint32 FJoinOptions =
);
Parameters
-
Name [in]
-
Specifies the domain or workgroup to join. Cannot be NULL.
-
Password [in]
-
If the UserName parameter specifies an account name, the Password parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.
-
UserName [in]
-
Pointer to a constant null-terminated character string that specifies the account name to use when connecting to the domain controller. Must specify a domain NetBIOS name and user account, for example, Domain\user. If this parameter is NULL, the caller information is used.
You can also use the user principal name (UPPED) in the form user@domain.
-
AccountOU [in]
-
Specifies the pointer to a constant null-terminated character string that contains the RFC 1779 format name of the organizational unit (OU) for the computer account. If you specify this parameter, the string must contain a full path, otherwise Accent must be NULL.
Example: "OU=testOU; DC=domain; DC=Domain; DC=com"
-
FJoinOptions [in]
-
Set of bit flags that define the join options.
-
(0)
-
Default. No join options.
-
NETSETUP_JOIN_DOMAIN (0x00000001)
-
Joins the computer to a domain. If this value is not specified, joins the computer to a workgroup.
-
NETSETUP_ACCT_CREATE (0x00000002)
-
Creates the account on the domain.
-
NETSETUP_WIN9X_UPGRADE (0x00000010)
-
The join operation is occurring as part of an upgrade.
-
NETSETUP_DOMAIN_JOIN_IF_JOINED (0x00000020)
-
Allows a join to a new domain even if the computer is already joined to a domain.
-
NETSETUP_JOIN_UNSECURE (0x00000040)
-
Performs an unsecured join.
This option requests a domain join to a pre-created account without authenticating with domain user credentials. This option can be used in conjunction with NETSETUP_MACHINE_PWD_PASSED option. In this case, Password is the password of the pre-created machine account.
Prior to Windows Vista with SP1 and Windows Server 2008, an unsecure join did not authenticate to the domain controller. All communication was performed using a null (unauthenticated) session. Starting with Windows Vista with SP1 and Windows Server 2008, the machine account name and password are used to authenticate to the domain controller.
-
NETSETUP_MACHINE_PWD_PASSED (0x00000080)
-
Indicates that the Password parameter specifies a local machine account password rather than a user password. This flag is valid only for unsecured joins, which you must indicate by also setting the NETSETUP_JOIN_UNSECURE flag.
If you set this flag, then after the join operation succeeds, the machine password will be set to the value of Password, if that value is a valid machine password.
-
NETSETUP_DEFER_SPN_SET (0x00000100)
-
Indicates that the service principal name (SPN) and the DnsHostName properties on the computer object should not be updated at this time.
Typically, these properties are updated during the join operation. Instead, these properties should be updated during a subsequent call to the Rename method. These properties are always updated during the rename operation.
-
NETSETUP_JOIN_DC_ACCOUNT (0x00000200)
-
Allow the domain join if existing account is a domain controller.
Note
This flag is supported on Windows Vista and later.
-
NETSETUP_AMBIGUOUS_DC (0x00001000)
-
When joining the domain don't try to set the preferred domain controller in the registry.
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_NO_NETLOGON_CACHE (0x00002000)
-
When joining the domain don't create the Netlogon cache.
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_DONT_CONTROL_SERVICES (0x00004000)
-
When joining the domain don't force Netlogon service to start.
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_SET_MACHINE_NAME (0x00008000)
-
When joining the domain for offline join only, set target machine hostname and NetBIOS name.
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_FORCE_SPN_SET (0x00010000)
-
When joining the domain, override other settings during domain join and set the service principal name (SPN).
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_NO_ACCT_REUSE (0x00020000)
-
When joining the domain, do not reuse an existing account.
Note
This flag is supported on Windows 7, Windows Server 2008 R2, and later.
-
NETSETUP_IGNORE_UNSUPPORTED_FLAGS (0x10000000)
-
If this bit is set, unrecognized flags will be ignored by the JoinDomainOrWorkgroup function and NetJoinDomain will behave as if the flags were not set.
Return value
Returns a system error code, which may include one of the following numeric values. Any other number indicates an error. For additional error codes, see WMI Error Constants or WbemErrorEnum.
-
Success
-
0
-
5
-
Access is denied.
-
87
-
The parameter is incorrect.
-
110
-
The system cannot open the specified object.
-
1323
-
Unable to update the password.
-
1326
-
Logon failure: unknown username or bad password.
-
1355
-
The specified domain either does not exist or could not be contacted.
-
2224
-
The account already exists.
-
2691
-
The machine is already joined to the domain.
-
2692
-
The machine is not currently joined to a domain.
-
WBEM_E_ENCRYPTED_CONNECTION_REQUIRED
-
0x80041087
Password and UserName are specified but the authentication level is not RPC_C_AUTHN_LEVEL_PKT_PRIVACY. For Visual Basic, wbemErrEncryptedConnectionRequired is returned.
-
Other
-
1 4294967295
Remarks
When moving a computer from a domain to a workgroup, you must remove the computer from the domain (with a call to UnjoinDomainOrWorkgroup) before calling this method to join a workgroup (with a call to JoinDomainOrWorkgroup). After calling this method, restart the affected computer to apply the changes.
UserName and Password can be left null. However, the authentication of the connection to WMI must be 6 in script or WbemAuthenticationLevelPktPrivacy in Visual Basic and other languages that can use the wbemdisp.dll library. For more information, see Setting the Default Process Security Level Using VBScript.
In C++, set the authentication at RPC_C_AUTHN_LEVEL_PKT_PRIVACY either in CoInitializeSecurity, for the entire process, or in CoSetProxyBlanket, for a connection to the IWbemServices proxy. For more information, see Setting Authentication Using C++ and Setting the Security on IWbemServices and Other Proxies.
Examples
The following VBScript code example joins a computer to a domain and creates the computer's account in Active Directory.
Const JOIN_DOMAIN = 1
Const ACCT_CREATE = 2
Const ACCT_DELETE = 4
Const WIN9X_UPGRADE = 16
Const DOMAIN_JOIN_IF_JOINED = 32
Const JOIN_UNSECURE = 64
Const MACHINE_PASSWORD_PASSED = 128
Const DEFERRED_SPN_SET = 256
Const INSTALL_INVOCATION = 262144
strDomain = "FABRIKAM"
strPassword = "ls4k5ywA"
strUser = "shenalan"
Set objNetwork = CreateObject("WScript.Network")
strComputer = objNetwork.ComputerName
Set objComputer = GetObject("winmgmts:{impersonationLevel=Impersonate}!\\" & strComputer & _
"\root\cimv2:Win32_ComputerSystem.Name='" & strComputer & "'")
ReturnValue = objComputer.JoinDomainOrWorkGroup(strDomain, _
strPassword, _
strDomain & "\" & strUser, _
NULL, _
JOIN_DOMAIN + ACCT_CREATE)
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows Vista |
| Minimum supported server |
Windows Server 2008 |
| Namespace |
Root\CIMV2 |
| MOF |
|
| DLL |
|