JoinDomainOrWorkgroup

Adds a computer system to a domain or workgroup.

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.

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.

Example

Do not run below example code just to see what happens next. Many methods seriously affect your system. Always make sure you actually understand what the method and the code do.

param
(
  [Parameter(Mandatory)]
  [String]
  $AccountOU,

  [Parameter(Mandatory)]
  [UInt32]
  $FJoinOptions,

  [Parameter(Mandatory)]
  [String]
  $Name,

  [Parameter(Mandatory)]
  [String]
  $Password,

  [Parameter(Mandatory)]
  [String]
  $UserName
)


$query = 'Select * From Win32_ComputerSystem'

Invoke-CimMethod -Query $query -MethodName JoinDomainOrWorkgroup -Arguments $PSBoundParameters |
  Add-Member -MemberType ScriptProperty -Name ReturnValueFriendly -Passthru -Value {
  switch ([int]$this.ReturnValue)
  {
        0        {'Success'}
        default  {"Unknown Error $_"}
    }
}

To run this method on one or more remote systems, use New-CimSession:

param
(
  [Parameter(Mandatory)]
  [String]
  $AccountOU,

  [Parameter(Mandatory)]
  [UInt32]
  $FJoinOptions,

  [Parameter(Mandatory)]
  [String]
  $Name,

  [Parameter(Mandatory)]
  [String]
  $Password,

  [Parameter(Mandatory)]
  [String]
  $UserName,

  [String[]]
  $ComputerName,

  [PSCredential]
  $Credential
)


$session = New-CimSession -ComputerName $ComputerName -Credential $Credential

$query = 'Select * From Win32_ComputerSystem'

Invoke-CimMethod -Query $query -MethodName JoinDomainOrWorkgroup -Arguments $PSBoundParameters -CimSession $session |
  Add-Member -MemberType ScriptProperty -Name ReturnValueFriendly -Passthru -Value {
  switch ([int]$this.ReturnValue)
  {
        0        {'Success'}
        default  {"Unknown Error $_"}
    }
}


Remove-CimSession -CimSession $session

Learn more about Invoke-CimMethod and invoking WMI methods.

Syntax

uint32 JoinDomainOrWorkgroup(
  [in] string Name,
  [in] string Password,
  [in] string UserName,
  [in] string AccountOU,
  [in] uint32 FJoinOptions = 
);

Parameters

Name Type Description
AccountOU String The AccountOU optionally 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, for example, OU=testOU, DC=domain, DC=Domain,DC=com. Otherwise, this parameter must be NULL.
FJoinOptions UInt32 The FJoinOptions parameter contains a set of bit flags defining the join options. This parameter can be one or more of the following values:
Join Domain - Joins the computer to a domain. If this value is not specified, joins the computer to a workgroup. 0 bit - Join Domain - If not present, a workgroup is joined.
1 bit - Acct Create - Creates the account on the domain.
2 bit - Acct Delete - Delete the account when a domain is left.
4 bit - Win9X Upgrade - The join operation is occurring as part of an upgrade of Windows 95/98 to Windows NT/Windows 2000.
5 bit - Domain Join If Joined - Allows a join to a new domain even if the computer is already joined to a domain.
6 bit - Join Unsecure - Performs an unsecured join.
7 bit - Machine Password Passed - Indicates that the machine (not user) password is passed. This option is only valid for unsecure joins
8 bit - Deferred SPN Set - Specifies that writing SPN and DnsHostName attributes on the computer object should be deferred until the rename that will follow the join.
18 bit - Install Invocation - The APIs were invoked during install.

The method returns a 0 if no options are involved.
Name String The Name parameter specifies the domain or workgroup to join. This parameter cannot be NULL.
Password String 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.
Password and Username must use a high authentication level (i.e. no less than RPC_C_AUTHN_LEVEL_PKT_PRIVACY) when they connect to winmgmt (i.e. in the call to obtain the IWbemServices interface) or SetProxyBlanket on their IWbemServices ptr. If they are local to winmgmt then this is not a concern because their authentication level is as good as RPC_C_AUTHN_LEVEL_PKT_PRIVACY as well as their client request never goes over the wire to get to the winmgmt.
If Password and Username are left null, the provider does not care.
If the provider determines that the authentication level is too low and a Password or Username has been specified then WBEM_E_ENCRYPTED_CONNECTION_REQUIRED will be returned.
UserName String The Username parameter is a pointer to a constant null-terminated character string that specifies the account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, “REDMOND\user”) or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, “[email protected]”). If this parameter is NULL, the caller’s context is used.
Password and Username must use a high authentication level (i.e. no less than RPC_C_AUTHN_LEVEL_PKT_PRIVACY) when they connect to winmgmt (i.e. in the call to obtain the IWbemServices interface) or SetProxyBlanket on their IWbemServices ptr. If they are local to winmgmt then this is not a concern because their authentication level is as good as RPC_C_AUTHN_LEVEL_PKT_PRIVACY as well as their client request never goes over the wire to get to the winmgmt.
If Password and Username are left null, the provider does not care.
If the provider determines that the authentication level is too low and a Password or Username has been specified then WBEM_E_ENCRYPTED_CONNECTION_REQUIRED will be returned.

FJoinOptions

[Flags()]Enum ComputerSystemFJoinOptions
{
  JoinDomain              = 1        # Joins the computer to a domain. If this value is not specified, joins the computer to a workgroup.
  AccountCreate           = 2        # Creates the account on the domain.
  Reserved1               = 4        # 
  Reserved2               = 8        # 
  Upgrade                 = 16       # The join operation is occurring as part of an upgrade.
  JoinIfJoined            = 32       # Allows a join to a new domain even if the computer is already joined to a domain.
  JoinUnsecure            = 64       # Performs an unsecured join. This option requests a domain join to a pre-created account without authenticating with domain user credentials.
  MachinePwdPassed        = 128      # 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 *JoinUnsecure* 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.
  DeferSpnSet             = 256      # 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.
  JoinDCAccount           = 512      # Allow the domain join if existing account is a domain controller.
  Reserved3               = 1024     # 
  Reserved4               = 2048     # 
  AmbiguousDC             = 4096     # When joining the domain don't try to set the preferred domain controller in the registry.
  NoNetlogonCache         = 8192     # When joining the domain don't create the Netlogon cache.
  DontControlServices     = 16384    # When joining the domain don't force Netlogon service to start.
  SetMachineName          = 32768    # When joining the domain for offline join only, set target machine hostname and NetBIOS name.
  ForceSPNSet             = 65536    # When joining the domain, override other settings during domain join and set the service principal name (SPN).
  NoAccountReuse          = 131072   # When joining the domain, do not reuse an existing account.
  IgnoreUnsupportedFlag   = 268435456 # 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 value of type UInt32. Return values:

$returnValues = @{
    0    = 'Success'
}

See Also

Additional methods implemented by Win32_ComputerSystem:

Rename()

Rename() renames a local computer.

SetPowerState()

SetPowerState() not implemented.

UnjoinDomainOrWorkgroup()

UnjoinDomainOrWorkgroup() removes a computer system from a domain or workgroup.

Requirements

To use Win32_ComputerSystem, the following requirements apply:

PowerShell

Get-CimInstance was introduced with PowerShell Version 3.0, which in turn was introduced on clients with Windows 8 and on servers with Windows Server 2012.

If necessary, update Windows PowerShell to Windows PowerShell 5.1, or install PowerShell 7 side-by-side.

Operating System

Win32_ComputerSystem was introduced on clients with Windows Vista and on servers with Windows Server 2008.

Namespace

Win32_ComputerSystem lives in the Namespace Root/CIMV2. This is the default namespace. There is no need to use the -Namespace parameter in Get-CimInstance.

Implementation

Win32_ComputerSystem is implemented in CIMWin32.dll and defined in CIMWin32.mof. Both files are located in the folder C:\Windows\system32\wbem:

explorer $env:windir\system32\wbem
notepad $env:windir\system32\wbem\CIMWin32.mof