Функция NetProvisionComputerAccount (lmjoin.h)

Статья
01/27/2024

Функция 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, которая содержит имя в формате 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	Используйте пароль учетной записи компьютера по умолчанию, который представляет собой имя компьютера в нижнем регистре. Это в значительной степени предназначено для поддержки более старой небезопасной модели присоединения, где предварительно созданная учетная запись обычно использует этот пароль по умолчанию. Примечание Приложения не должны использовать этот параметр, если это возможно. Этот параметр, а также функция NetJoinDomain с параметром dwOptions, для NETSETUP_JOIN_UNSECURE для небезопасного соединения следует использовать только в более ранних версиях Windows.
NETSETUP_PROVISION_SKIP_ACCOUNT_SEARCH 0x00000008	Не пытайтесь найти учетную запись на контроллере домена в домене. Этот параметр ускоряет операцию, но его следует использовать только в том случае, если вызывающий объект уверен, что учетная запись с таким же именем не была создана недавно. Этот параметр действителен, только если указан параметр lpDcName . При выполнении предварительных требований этот параметр позволяет ускорить подготовку, полезную для таких сценариев, как пакетная обработка.
NETSETUP_PROVISION_ROOT_CA_CERTS 0x00000010	Этот параметр извлекает все корневые сертификаты центра сертификации на локальном компьютере и добавляет их в пакет подготовки, если в составе пакета подготовки не указаны имена шаблонов сертификатов (член aCertTemplateNamesструктуры NETSETUP_PROVISIONING_PARAMS , передаваемый в параметре pProvisioningParams в функцию NetCreateProvisioningPackage , имеет значение NULL). Примечание Этот флаг поддерживается функцией NetCreateProvisioningPackage только в Windows 8, Windows Server 2012 и более поздних версиях.

[out, optional] pProvisionBinData

Необязательный указатель, который получит непрозрачный двоичный BLOB-объект сериализованных метаданных, необходимых функции NetRequestOfflineDomainJoin для завершения автономного присоединения к домену, если функция NetProvisionComputerAccount успешно завершена. Данные возвращаются в виде непрозрачного двоичного буфера, который может быть передан в функцию NetRequestOfflineDomainJoin .

Если этот параметр имеет значение NULL, параметр pProvisionTextData не должен иметь значение NULL. Если этот параметр не имеет значение NULL, то параметр pProvisionTextData должен иметь значение NULL.

[out, optional] pdwProvisionBinDataSize

Указатель на значение, которое получает размер (в байтах) буфера, возвращаемого в параметре pProvisionBinData .

Этот параметр не должен иметь значение NULL , если параметр pProvisionBinData не имеет значения NULL. Этот параметр должен иметь значение NULL , если параметр pProvisionBinData имеет значение NULL.

[out, optional] pProvisionTextData

Необязательный указатель, который получит непрозрачный двоичный BLOB-объект сериализованных метаданных, необходимых функции NetRequestOfflineDomainJoin для завершения автономного присоединения к домену, если функция NetProvisionComputerAccount успешно завершена. Данные возвращаются в строковой форме для внедрения в файл ответов автоматической установки.

Если этот параметр имеет значение 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	Учетная запись уже существует в домене, и бит NETSETUP_PROVISION_REUSE_ACCOUNT не был указан в параметре dwOptions .
NERR_WkstaNotStarted	Служба рабочей станции не запущена.
RPC_S_CALL_IN_PROGRESS	Удаленный вызов процедуры для этого потока уже выполняется.
RPC_S_PROTSEQ_NOT_SUPPORTED	Последовательность протокола удаленного вызова процедур не поддерживается.

Функция NetProvisionComputerAccount поддерживается в Windows 7 и Windows Server 2008 R2 для операций автономного соединения. В Windows 8 или Windows Server 2008 R2 рекомендуется использовать функцию NetCreateProvisioningPackage вместо функции NetProvisionComputerAccount.

Функция NetProvisionComputerAccount используется для подготовки учетной записи компьютера для последующего использования в операции автономного присоединения к домену с помощью функции NetRequestOfflineDomainJoin . В сценарии автономного присоединения к домену эти функции используются следующим образом:

NetProvisionComputerAccount — это функция подготовки, которая сначала вызывается для выполнения сетевых операций, необходимых для создания и настройки объекта-компьютера в Active Directory. Выходные данные NetProvisionComputerAccount представляют собой непрозрачный двоичный BLOB-объект сериализованных метаданных, используемых для следующего шага.
Затем вызывается функция инициализации образа NetRequestOfflineDomainJoin, чтобы внедрить выходные данные функции подготовки NetProvisionComputerAccount в образ операционной системы Windows, который будет использоваться во время установки.

Изменения в коде инициализации Windows обнаруживают это сохраненное состояние и влияют на локальную только часть присоединения к домену.

Функция NetProvisionComputerAccount создает или повторно использует учетную запись компьютера в домене, собирает все необходимые метаданные и возвращает их в непрозрачный двоичный BLOB-объект с управлением версиями или в виде текста для внедрения в файл ответов автоматической установки. Непрозрачный двоичный BLOB-объект может использоваться операцией запроса автономного присоединения к домену, предоставляя все необходимые входные данные для завершения присоединения к домену во время первой загрузки без каких-либо сетевых операций (только обновления локального состояния).

Примечание по безопасности: Большой двоичный объект, возвращаемый функцией NetProvisionComputerAccount , содержит очень конфиденциальные данные. Он должен рассматриваться так же безопасно, как пароль в виде открытого текста. Большой двоичный объект содержит пароль учетной записи компьютера и другие сведения о домене, включая доменное имя, имя контроллера домена и идентификатор безопасности (SID) домена. Если большой двоичный объект транспортируется физически или по сети, необходимо соблюдать осторожность для его безопасной транспортировки. Проект не предусматривает никаких положений для защиты этих данных. Эта проблема возникает в настоящее время с файлами ответов автоматической установки, которые могут содержать ряд секретов, включая пароли пользователей домена. Вызывающий объект должен защитить большой двоичный объект и файлы автоматической установки. Решения этой проблемы разнообразны. Например, предварительно обмениваемые ключи можно использовать для шифрования сеанса между потребителем и сущностью подготовки, что обеспечивает безопасную передачу непрозрачного BLOB-объекта.

Непрозрачный BLOB-объект, возвращаемый в параметре pProvisionBinData функцией NetProvisionComputerAccount , имеет версию, чтобы обеспечить совместимость и удобство обслуживания между разными версиями Windows (присоединение клиента, компьютера подготовки и контроллера домена). Сценарий автономного присоединения в настоящее время не ограничивает время существования большого двоичного объекта, возвращаемого функцией NetProvisionComputerAccount .

При автономном присоединении к домену проверка доступа зависит от конфигурации домена. Создание учетной записи компьютера включено тремя способами:

Администраторы домена имеют права на создание учетных записей компьютеров.
Sd в контейнере может делегировать права на создание учетных записей компьютеров.
По умолчанию пользователи, прошедшие проверку подлинности, могут создавать учетные записи компьютеров по привилегиям. Пользователи, прошедшие проверку подлинности, могут создавать ограниченное количество учетных записей, указанных в качестве квоты в домене (значение по умолчанию — 10). Дополнительные сведения см. в описании атрибута ms-DS-MachineAccountQuota в схеме Active Directory.

Функция NetProvisionComputerAccount работает только с контроллером домена, доступного для записи, и не работает с контроллером домена только для чтения. После того как подготовка выполняется для контроллера домена, доступного для записи, и учетная запись реплицируется на контроллер домена только для чтения, другие части операции автономного присоединения к домену не требуют доступа к контроллеру домена.

Если функция NetProvisionComputerAccount выполнена успешно, возвращается указатель в параметре pProvisionBinData или pProvisionTextData (в зависимости от того, какой параметр был не null) с сериализованными данными для использования в операции автономного соединения или в виде текста в файле автоматической установки.

Дополнительные сведения об операциях автономного присоединения к домену см. в пошаговом руководстве по автономному присоединению к домену.

Присоединение (и разъединение) компьютера с доменом с помощью NetJoinDomain и NetUnjoinDomain может выполнять только член локальной группы Администраторы на целевом компьютере. Обратите внимание, что администратор домена может задать дополнительные требования для присоединения к домену с помощью делегирования и назначения привилегий.

Требования


Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	lmjoin.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll