Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
JoinDomainOrWorkgroup method
Collapse the table of content
Expand the table of content

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 = 0
);

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.

ValueMeaning
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

Return code/valueDescription
Success
0
5

Access is denied.

87

The parameter is incorrect.

110

he 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 Join a computer to a domain PowerShell example joins a computer to a domain.

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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Namespace

Root\CIMV2

MOF

CIMWin32.mof

DLL

CIMWin32.dll

See also

Win32_ComputerSystem
UnjoinDomainOrWorkgroup method

 

 

Show:
© 2015 Microsoft