Share via

3.2.4.22 NetrJoinDomain3 (Opnum 31)

  • Article

The NetrJoinDomain3 method uses encrypted credentials to join a computer to a domain or to a workgroup.<124>

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

 unsigned long NetrJoinDomain3(
   [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_AES 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 (1) MUST ignore this parameter.

DomainNameParam: A pointer to a string that specifies the domain name (1) 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) (1) 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\NetBIOS name

MachineAccountOU: A pointer to a string that contains the format name of the organizational unit (OU) directory object under which the machine account directory object is created (see [RFC1777]). 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_AES structure (section 2.2.5.19) 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 behavior in message processing.<125>

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<126> 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<127> be updated at this time, but instead SHOULD<128> be updated during a subsequent call to NetrRenameMachineInDomain2 (section 3.2.4.15).

NETSETUP_JOIN_DC_ACCOUNT

0x00000200

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

NETSETUP_JOIN_WITH_NEW_NAME

0x00000400

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

NETSETUP_JOIN_READONLY

0x00000800

Specifies that the join SHOULD<132>  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 username 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.<133>

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 NetrJoinDomain3 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.22.1 specifies the message processing that is common to both domain and workgroup joins.

  • Section 3.2.4.22.2  specifies the state transition associated with a domain join.

Several password data elements are involved in message processing for the NetrJoinDomain3 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 (1) 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.

ComputerPasswordString: The ASCII string that contains the plaintext form of the password for the computer account.