NetProvisionComputerAccount function (lmjoin.h)

The NetProvisionComputerAccount function provisions a computer account for later use in an offline domain join operation.

Syntax

NET_API_STATUS NET_API_FUNCTION NetProvisionComputerAccount(
  [in]            LPCWSTR lpDomain,
  [in]            LPCWSTR lpMachineName,
  [in, optional]  LPCWSTR lpMachineAccountOU,
  [in, optional]  LPCWSTR lpDcName,
  [in]            DWORD   dwOptions,
  [out, optional] PBYTE   *pProvisionBinData,
  [out, optional] DWORD   *pdwProvisionBinDataSize,
  [out, optional] LPWSTR  *pProvisionTextData
);

Parameters

[in] lpDomain

A pointer to a NULL-terminated character string that specifies the name of the domain where the computer account is created.

[in] lpMachineName

A pointer to a NULL-terminated character string that specifies the short name of the machine from which the computer account attribute sAMAccountName is derived by appending a '$'. This parameter must contain a valid DNS or NetBIOS machine name.

[in, optional] lpMachineAccountOU

An optional pointer to a NULL-terminated character string that contains the RFC 1779 format name of the organizational unit (OU) where the computer account will be created. 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.

If this parameter is NULL, the well known computer object container will be used as published in the domain.

[in, optional] lpDcName

An optional pointer to a NULL-terminated character string that contains the name of the domain controller to target.

[in] dwOptions

A set of bit flags that define provisioning options. This parameter can be one or more of the following values defined in the Lmjoin.h header file.

[out, optional] pProvisionBinData

An optional pointer that will receive the opaque binary blob of serialized metadata required by NetRequestOfflineDomainJoin function to complete an offline domain join, if the NetProvisionComputerAccount function completes successfully. The data is returned as an opaque binary buffer which may be passed to NetRequestOfflineDomainJoin function.

If this parameter is NULL, then pProvisionTextData parameter must not be NULL. If this parameter is not NULL, then the pProvisionTextData parameter must be NULL.

[out, optional] pdwProvisionBinDataSize

A pointer to a value that receives the size, in bytes, of the buffer returned in the pProvisionBinData parameter.

This parameter must not be NULL if the pProvisionBinData parameter is not NULL. This parameter must be NULL when the pProvisionBinData parameter is NULL.

[out, optional] pProvisionTextData

An optional pointer that will receive the opaque binary blob of serialized metadata required by NetRequestOfflineDomainJoin function to complete an offline domain join, if the NetProvisionComputerAccount function completes successfully. The data is returned in string form for embedding in an unattended setup answer file.

If this parameter is NULL, then the pProvisionBinData parameter must not be NULL. If this parameter is not NULL, then the pProvisionBinData parameter must be NULL.

Return value

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the system error codes.

Remarks

The NetProvisionComputerAccount function is supported on Windows 7 and Windows Server 2008 R2 for offline join operations. On Windows 8 or Windows Server 2008 R2, it is recommended that the NetCreateProvisioningPackage function be used instead of the NetProvisionComputerAccount function.

The NetProvisionComputerAccount function is used to provision a computer account for later use in an offline domain join operation using the NetRequestOfflineDomainJoin function. The offline domain join scenario uses these functions as follows:

• NetProvisionComputerAccount is a provisioning function that is first called to perform the network operations necessary to create and configure the computer object in Active Directory. The output from the NetProvisionComputerAccount is an opaque binary blob of serialized metadata used for the next step.
• NetRequestOfflineDomainJoin, an image initialization function, is then called to inject the output from the NetProvisionComputerAccount provisioning function into a Windows operating system image to be used during installation.

The NetProvisionComputerAccount function will create or reuse the machine account in the domain, collect all necessary metadata and return it in an opaque versioned binary blob or as text for embedding in an unattended setup answer file. The opaque binary blob can be consumed by the offline domain join request operation supplying all the necessary input to complete the domain join during first boot without any network operations (local state updates only).

Security Note:  The blob returned by the NetProvisionComputerAccount function contains very sensitive data. It should be treated just as securely as a plaintext password. The blob contains the machine account password and other information about the domain, including the domain name, the name of a domain controller, and the security ID (SID) of the domain. If the blob is being transported physically or over the network, care must be taken to transport it securely. The design makes no provisions for securing this data. This problem exists today with unattended setup answer files which can carry a number of secrets including domain user passwords. The caller must secure the blob and the unattended setup files. Solutions to this problem are varied. As an example, a pre-exchanged key could be used to encrypt a session between the consumer and provisioning entity enabling a secure transfer of the opaque blob.

The opaque blob returned in the pProvisionBinData parameter by the NetProvisionComputerAccount function is versioned to allow interoperability and serviceability scenarios between different versions of Windows (joining client, provisioning machine, and domain controller). The offline join scenario currently does not limit the lifetime of the blob returned by the NetProvisionComputerAccount function.

For offline domain joins, the access check performed depends on the configuration of the domain. Computer account creation is enabled using three methods:

• Domain administrators have rights to create computer accounts.
• The SD on a container can delegate the rights to create computer accounts.
• By default, authenticated users may create computer accounts by privilege. Authenticated users are limited to creating a limited number of accounts that is specified as a quota on the domain (the default value is 10). For more information, see the ms-DS-MachineAccountQuota attribute in the Active Directory schema.

The NetProvisionComputerAccount function works only with a writable domain controller and does not function against a read-only domain controller. Once provisioning is done against a writable domain controller and the account is replicated to a read-only domain controller, then the other portions of offline domain join operation do not require access to a domain controller.

If the NetProvisionComputerAccount function is successful, the pointer in the pProvisionBinData or pProvisionTextData parameter (depending on which was parameter was not NULL) is returned with the serialized data for use in an offline join operation or as text in an unattended setup file.

For more information on offline domain join operations, see the Offline Domain Join Step-by-Step Guide.

Joining (and unjoining) a computer to a domain using NetJoinDomain and NetUnjoinDomain can be performed only by a member of the Administrators local group on the target computer. Note that the domain administrator can set additional requirements for joining the domain using delegation and assignment of privileges.

Requirements

See also

NetCreateProvisioningPackage

NetJoinDomain

NetRenameMachineInDomain

NetRequestOfflineDomainJoin

NetUnjoinDomain

Network Management Functions

Network Management Overview

Offline Domain Join Step-by-Step Guide

ms-DS-MachineAccountQuota