3.2.4.13 NetrJoinDomain2 (Opnum 22)

Article
04/27/2022

The NetrJoinDomain2 method uses encrypted credentials to join a computer to a domain or a workgroup.<57>

For high-level, informative discussions about domain controller location and domain join and unjoin, see [MS-ADOD] sections 2.7.7 and 3.1. For more information, see the example in section 4.3.

 unsigned long NetrJoinDomain2(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string] wchar_t* DomainNameParam,
   [in, string, unique] wchar_t* MachineAccountOU,
   [in, string, unique] wchar_t* AccountName,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD Password,
   [in] unsigned long Options
 );

RpcBindingHandle: An RPC binding handle [C706].

ServerName: This parameter has no effect on message processing in any environment. The client MUST set this parameter to a value that resolves to the IP protocol layer destination address of the RPC packets it transmits ([MS-RPCE] section 2.1.1.2). The server (2) MUST ignore this parameter.

DomainNameParam: A pointer to a string that specifies the domain name (2) or workgroup name to join, and optionally the domain controller machine name within the domain. This parameter MUST NOT be NULL.

If the string specifies the name of the preferred domain controller to perform the join operation, the string MUST be of the form DomainNameToJoin\MachineName, where DomainNameToJoin is the domain to join, "\" is a delimiter, and MachineName is the name of the domain controller to perform the join operation. In all cases, the DomainNameToJoin portion of this parameter MUST be either the NetBIOS name of the domain or the fully qualified domain name (FQDN) (2) of the domain. If the MachineName is passed, it MUST be either the NetBIOS name of the domain controller or the Internet host name of the domain controller. The format of DomainNameToJoin places no constraint on the format of MachineName and vice versa; thus, each of the following permutations are accepted:

NetBIOS name\NetBIOS name
NetBIOS name\Internet host name
FQDN (2)\NetBIOS name

MachineAccountOU: A pointer to a string that contains [RFC1777] the format name of the organizational unit (OU) directory object under which the machine account directory object is created. This parameter is optional. If specified, this string MUST contain the full path; for example, OU=testOU,DC=domain,DC=Domain,DC=com.

AccountName: A pointer to a string that specifies an account name in the domain DomainNameParam to use when connecting to a domain controller. This parameter is optional. If this parameter is NULL, the caller's account name MUST be used. If this parameter is specified, the format MUST be one of the following:

<NetBIOSDomainName>\<UserName>
<FullyQualifiedDNSDomainName>\<UserName>
<UserName>@<FullyQualifiedDNSDomainName>

Password: A pointer to a JOINPR_ENCRYPTED_USER_PASSWORD structure (section 2.2.5.18) that specifies the encrypted password to use with the AccountName parameter. Sections 3.2.4.13.1 and 3.2.4.13.3 specify the processing of this parameter.

Options: A 32-bit bitfield that specifies modifications to default server (2) behavior in message processing.<58>

Value/code	Meaning
NETSETUP_JOIN_DOMAIN 0x00000001	Joins the computer to a domain. The default action is to join the computer to a workgroup.
NETSETUP_ACCT_CREATE 0x00000002	Creates the account on the domain. The name is the persisted abstract state ComputerNameNetBIOS (section 3.2.1.5) unless this behavior is altered by another option such as NETSETUP_JOIN_WITH_NEW_NAME.
NETSETUP_ACCT_DELETE 0x00000004	Disables the old account when the join operation occurs on a computer that is already joined to a domain. Important This flag is neither supported nor tested for use with NetrJoinDomain2; therefore, its use is not specified in any message processing.
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. It MUST be used only in conjunction with the NETSETUP_MACHINE_PWD_PASSED flag.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Indicates that the Password parameter SHOULD <59> specify the password for the machine joining the domain. This flag is valid for unsecured joins, which are indicated by setting the NETSETUP_JOIN_UNSECURE flag, or for read-only joins, which are indicated by setting the NETSETUP_JOIN_READONLY flag. If this flag is set, the value of Password determines the value stored for the computer password during the join process.
NETSETUP_DEFER_SPN_SET 0x00000100	Indicates that the service principal name (SPN) and the DnsHostName properties on the computer SHOULD NOT <60> be updated at this time, but instead SHOULD <61> be updated during a subsequent call to NetrRenameMachineInDomain2 (section 3.2.4.15).
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Indicates that the join SHOULD <62> be allowed if an existing account exists and it is a domain controller account.<63>
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Indicates that the join SHOULD <64>occur using the new computer name.
NETSETUP_JOIN_READONLY 0x00000800	Specifies that the join SHOULD <65> be performed in a read-only manner against an existing account object. This option is intended to enable the server to join a domain using a read-only domain controller.
NETSETUP_INSTALL_INVOCATION 0x00040000	Indicates that the protocol method was invoked during installation.

Value/code

Meaning

NETSETUP_JOIN_DOMAIN

0x00000001

Joins the computer to a domain. The default action is to join the computer to a workgroup.

NETSETUP_ACCT_CREATE

0x00000002

Creates the account on the domain. The name is the persisted abstract state ComputerNameNetBIOS (section 3.2.1.5) unless this behavior is altered by another option such as NETSETUP_JOIN_WITH_NEW_NAME.

NETSETUP_ACCT_DELETE

0x00000004

Disables the old account when the join operation occurs on a computer that is already joined to a domain.

Important This flag is neither supported nor tested for use with NetrJoinDomain2; therefore, its use is not specified in any message processing.

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. It MUST be used only in conjunction with the NETSETUP_MACHINE_PWD_PASSED flag.

NETSETUP_MACHINE_PWD_PASSED

0x00000080

Indicates that the Password parameter SHOULD <59> specify the password for the machine joining the domain.

This flag is valid for unsecured joins, which are indicated by setting the NETSETUP_JOIN_UNSECURE flag, or for read-only joins, which are indicated by setting the NETSETUP_JOIN_READONLY flag. If this flag is set, the value of Password determines the value stored for the computer password during the join process.

NETSETUP_DEFER_SPN_SET

0x00000100

Indicates that the service principal name (SPN) and the DnsHostName properties on the computer SHOULD NOT <60> be updated at this time, but instead SHOULD <61> be updated during a subsequent call to NetrRenameMachineInDomain2 (section 3.2.4.15).

NETSETUP_JOIN_DC_ACCOUNT

0x00000200

Indicates that the join SHOULD <62> be allowed if an existing account exists and it is a domain controller account.<63>

NETSETUP_JOIN_WITH_NEW_NAME

0x00000400

Indicates that the join SHOULD <64>occur using the new computer name.

NETSETUP_JOIN_READONLY

0x00000800

Specifies that the join SHOULD <65> be performed in a read-only manner against an existing account object. This option is intended to enable the server to join a domain using a read-only domain controller.

NETSETUP_INSTALL_INVOCATION

0x00040000

Indicates that the protocol method was invoked during installation.

Return Values: When the message processing result meets the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code	Meaning
NERR_Success 0x00000000	The operation completed successfully.
ERROR_FILE_NOT_FOUND 0x00000002	The object was not found.
ERROR_ACCESS_DENIED 0x00000005	Access is denied.
ERROR_NOT_SUPPORTED 0x00000032	The request is not supported.
ERROR_INVALID_PASSWORD 0x00000056	The specified network password is not correct.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect.
ERROR_PASSWORD_RESTRICTION 0x0000052D	Unable to update the password. The value provided for the new password does not meet the length, complexity, or history requirements of the domain.
ERROR_LOGON_FAILURE 0x0000052E	Logon failure: unknown user name or bad password.
ERROR_NONE_MAPPED 0x00000534	The account was not found.
ERROR_INVALID_DOMAIN_ROLE 0x0000054A	The name of a domain controller was provided in the DomainNameParam parameter, and validation of that domain controller failed. Validation is specified in the message-processing steps for the section "Domain Join" later.
ERROR_NO_SUCH_DOMAIN 0x0000054B	The specified domain either does not exist or could not be contacted.
RPC_S_PROTSEQ_NOT_SUPPORTED 0x000006A7	The RPC protocol sequence is not supported.
RPC_S_CALL_IN_PROGRESS 0x000006FF	A remote procedure call is already in progress.<66>
NERR_UserExists 0x000008B0	The user account already exists.
NERR_SetupAlreadyJoined 0x00000A83	This computer is already joined to a domain.
NERR_SetupDomainController 0x00000A85	This computer is a domain controller and cannot be unjoined from a domain.
NERR_InvalidWorkgroupName 0x00000A87	The specified workgroup name is invalid.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

Message processing for the NetrJoinDomain2 method specifies the behavior of joining either a domain or a workgroup. The behavior of this method is covered in the following subsections:

Section 3.2.4.13.1 specifies the message processing that is common to both domain and workgroup joins.
Section 3.2.4.13.2 specifies the state transition associated with a domain join.
Section 3.2.4.13.3 specifies the message processing that is involved in a domain join.
Section 3.2.4.13.4 specifies the message processing that is involved in a workgroup join.

Several password data elements are involved in message processing for the NetrJoinDomain2 method, and they are distinguished as follows:

Password: A parameter to this method, either the password corresponding to the AccountName that is used to authenticate (2) at the domain controller or the password used for the computer account. The bits in the Options parameter determine how Password is used. This element is distinct from the client data model element Password that is defined in section 3.2.1.6.

PasswordString: The Unicode UTF-8 string that corresponds to the plaintext form of the password in Password. This variable is relevant to sections 3.2.4.13.1 and 3.2.4.13.3.

ComputerPasswordString: The ASCII string that contains the plaintext form of the password for the computer account. This variable is relevant to section 3.2.4.13.3.

3.2.4.13 NetrJoinDomain2 (Opnum 22)

Additional resources