NetProvisionComputerAccount 函数 (lmjoin.h)

  • 项目

NetProvisionComputerAccount 函数预配计算机帐户，以便以后在脱机域加入操作中使用。

语法

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

参数

[in] lpDomain

指向 以 NULL 结尾的字符串的指针，该字符串指定在其中创建计算机帐户的域的名称。

[in] lpMachineName

指向 以 NULL 结尾的字符串的指针，该字符串指定计算机帐户属性 sAMAccountName 通过追加“$”从中派生的计算机的短名称。 此参数必须包含有效的 DNS 或 NetBIOS 计算机名称。

[in, optional] lpMachineAccountOU

指向 以 NULL 结尾的字符串的可选指针，该字符串包含要在其中创建计算机帐户的组织单位 (OU) 的 RFC 1779 格式名称。 如果指定此参数，字符串必须包含完整路径，例如 OU=testOU，DC=domain，DC=Domain，DC=com。 否则，此参数必须为 NULL。

如果此参数为 NULL，则已知计算机对象容器将用作域中的发布。

[in, optional] lpDcName

指向以 NULL 结尾的字符串的可选指针，该字符串包含要作为目标的域控制器的名称。

[in] dwOptions

定义预配选项的一组位标志。 此参数可以是 Lmjoin.h 头文件中定义的以下一个或多个值。

值 含义
NETSETUP_PROVISION_DOWNLEVEL_PRIV_SUPPORT
0x00000001
 如果调用方需要按特权创建帐户，则此选项将导致使用帐户创建函数在失败时重试，从而启用与早期版本 Windows 上运行的域控制器的互操作性。

使用下层特权支持时，不支持 lpMachineAccountOU 。
NETSETUP_PROVISION_REUSE_ACCOUNT
0x00000002
 如果命名帐户已存在，则会尝试重复使用现有帐户。

此选项需要足够的凭据来执行此操作， (域管理员或对象所有者) 。
NETSETUP_PROVISION_USE_DEFAULT_PASSWORD
0x00000004
 使用默认的计算机帐户密码，该密码是小写的计算机名称。 这主要是为了支持较旧的不安全联接模型，其中预创建的帐户通常使用此默认密码。
注意 如果可能，应用程序应避免使用此选项。 此选项以及将 dwOptions 设置为 NETSETUP_JOIN_UNSECURE 的 NetJoinDomain 函数应仅在早期版本的 Windows 上使用。
 
NETSETUP_PROVISION_SKIP_ACCOUNT_SEARCH
0x00000008
 请勿尝试在域中的任何域控制器上查找帐户。 此选项可加快操作速度，但仅当调用方确定最近尚未创建同名帐户时，才应使用此选项。

仅当指定 lpDcName 参数时，此选项才有效。 当满足先决条件时，此选项允许必须更快地预配对批处理等方案有用。
NETSETUP_PROVISION_ROOT_CA_CERTS
0x00000010
 此选项检索本地计算机上的所有根证书颁发机构证书，并在没有证书模板名称作为预配包的一部分提供时， (pProvisioningParams 参数中传递到 NetCreateProvisioningPackage 函数的NETSETUP_PROVISIONING_PARAMS结构的 aCertTemplateNames 成员为 NULL) 时，将其添加到预配包中。
注意此标志仅受 Windows 8、Windows Server 2012 及更高版本上的 NetCreateProvisioningPackage 函数支持。
 

[out, optional] pProvisionBinData

如果 NetProvisionComputerAccount 函数成功完成，该指针将接收 NetRequestOfflineDomainJoin 函数完成脱机域加入所需的序列化元数据的不透明二进制 Blob。 数据作为不透明的二进制缓冲区返回，该缓冲区可能传递给 NetRequestOfflineDomainJoin 函数。

如果此参数为 NULL，则 pProvisionTextData 参数不得为 NULL。 如果此参数不为 NULL，则 pProvisionTextData 参数必须为 NULL。

[out, optional] pdwProvisionBinDataSize

指向一个值的指针，该值接收 pProvisionBinData 参数中返回的缓冲区的大小（以字节为单位）。

如果 pProvisionBinData 参数不为 NULL，则此参数不得为 NULL。 当 pProvisionBinData 参数为 NULL 时，此参数必须为 NULL。

[out, optional] pProvisionTextData

如果 NetProvisionComputerAccount 函数成功完成，该指针将接收 NetRequestOfflineDomainJoin 函数完成脱机域加入所需的序列化元数据的不透明二进制 Blob。 数据以字符串形式返回，用于嵌入无人参与安装应答文件中。

如果此参数为 NULL，则 pProvisionBinData 参数不得为 NULL。 如果此参数不为 NULL，则 pProvisionBinData 参数必须为 NULL。

返回值

如果函数成功，则返回值NERR_Success。

如果函数失败，则返回值可以是以下错误代码之一或 系统错误代码之一。

返回代码 说明
ERROR_ACCESS_DENIED
 访问被拒绝。 如果调用方没有足够的权限来完成操作，则返回此错误。
ERROR_INVALID_DOMAIN_ROLE
 只允许域的主域控制器执行此操作。 如果在 lpDcName 参数中指定了域控制器名称，但无法将指定的计算机验证为 lpDomain 参数中指定的目标域的域控制器，则返回此错误。
ERROR_INVALID_PARAMETER
 参数不正确。 如果 lpDomain 或 lpMachineName 参数为 NULL，则返回此错误。 如果 pProvisionBinData 和 pProvisionTextData 参数均为 NULL，也会返回此错误。
ERROR_NO_SUCH_DOMAIN
 指定的域不存在。
ERROR_NOT_SUPPORTED
 不支持该请求。 如果指定了 lpMachineAccountOU 参数，并且域控制器在不支持此参数的早期版本的 Windows 上运行，则返回此错误。
NERR_DS8DCRequired
 指定的域控制器不符合此操作的版本要求。
NERR_LDAPCapableDCRequired
 此操作需要支持 LDAP 的域控制器。
NERR_UserExists
 帐户已存在于域中，并且 dwOptions 参数中未指定NETSETUP_PROVISION_REUSE_ACCOUNT位。
NERR_WkstaNotStarted
 工作站服务尚未启动。
RPC_S_CALL_IN_PROGRESS
 此线程的远程过程调用已在进行中。
RPC_S_PROTSEQ_NOT_SUPPORTED
 不支持远程过程调用协议序列。

注解

Windows 7 和 Windows Server 2008 R2 支持 NetProvisionComputerAccount 函数进行脱机联接操作。 在 Windows 8 或 Windows Server 2008 R2 上，建议使用 NetCreateProvisioningPackage 函数而不是 NetProvisionComputerAccount 函数。

NetProvisionComputerAccount 函数用于预配计算机帐户，以便以后使用 NetRequestOfflineDomainJoin 函数在脱机域加入操作中使用。 脱机域加入方案使用以下函数，如下所示：

  • NetProvisionComputerAccount 是一个预配函数，首先调用它来执行在 Active Directory 中创建和配置计算机对象所需的网络操作。 NetProvisionComputerAccount 的输出是用于下一步的序列化元数据的不透明二进制 Blob。
  • 然后调用 NetRequestOfflineDomainJoin（映像初始化函数），将 NetProvisionComputerAccount 预配函数的输出注入到 Windows 操作系统映像中，以在安装期间使用。
对 Windows 初始化代码的更改将检测此保存的状态，并影响域加入的本地部分。

NetProvisionComputerAccount 函数将在域中创建或重复使用计算机帐户，收集所有必要的元数据，并在不透明的版本控制二进制 Blob 中返回它，或作为文本将其嵌入无人参与安装应答文件中。 脱机域加入请求操作可以使用不透明的二进制 Blob，该操作提供在首次启动期间完成域加入所需的全部输入，而无需任何网络操作 (本地状态更新) 。

安全说明： NetProvisionComputerAccount 函数返回的 Blob 包含非常敏感的数据。 它应与纯文本密码一样安全处理。 Blob 包含计算机帐户密码和有关域的其他信息，包括域名、域控制器的名称以及域的 SID) (安全 ID。 如果 Blob 以物理方式或通过网络传输，则必须注意安全地传输它。 该设计不对保护此数据作出任何规定。 目前，无人参与安装应答文件存在此问题，这些文件可能携带许多机密，包括域用户密码。 调用方必须保护 Blob 和无人参与安装文件。 此问题的解决方案各不相同。 例如，预交换的密钥可用于加密使用者和预配实体之间的会话，从而实现不透明 Blob 的安全传输。

NetProvisionComputerAccount 函数在 pProvisionBinData 参数中返回的不透明 blob 进行了版本控制，以允许不同版本的 Windows (联接客户端、预配计算机和域控制器) 之间的互操作性和可维护性方案。 脱机联接方案当前不限制 NetProvisionComputerAccount 函数返回的 Blob 的生存期。

对于脱机加入域，执行的访问检查取决于域的配置。 使用三种方法启用计算机帐户创建：

  • 域管理员有权创建计算机帐户。
  • 容器上的 SD 可以委托创建计算机帐户的权限。
  • 默认情况下，经过身份验证的用户可以按权限创建计算机帐户。 经过身份验证的用户仅限于在域中创建指定为配额的有限数量的帐户， (默认值为 10) 。 有关详细信息，请参阅 Active Directory 架构中的 ms-DS-MachineAccountQuota 属性。

NetProvisionComputerAccount 函数仅适用于可写域控制器，不适用于只读域控制器。 针对可写域控制器完成预配并将帐户复制到只读域控制器后，脱机加入操作的其他部分不需要访问域控制器。

如果 NetProvisionComputerAccount 函数成功，则 pProvisionBinData 或 pProvisionTextData 参数中的指针 (，具体取决于哪个 is 参数不为 NULL ，) 将随序列化数据一起返回，以便在脱机联接操作中使用或作为无人参与安装文件中的文本。

有关脱机加入域操作的详细信息，请参阅 脱机域加入分步指南。

使用 NetJoinDomain 和 NetUnjoinDomain 将) 计算机加入域和取消加入 (只能由目标计算机上的 Administrators 本地组的成员执行。 请注意，域管理员可以使用委派和权限分配来设置加入域的其他要求。

要求

   
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
目标平台 Windows
标头 lmjoin.h (包括 Lm.h)
Library Netapi32.lib
DLL Netapi32.dll

另请参阅

NetCreateProvisioningPackage

NetJoinDomain

NetRenameMachineInDomain

NetRequestOfflineDomainJoin

NetUnjoinDomain

网络管理功能

网络管理概述

脱机域加入分步指南

ms-DS-MachineAccountQuota