Función NetProvisionComputerAccount (lmjoin.h)
La función NetProvisionComputerAccount aprovisiona una cuenta de equipo para su uso posterior en una operación de unión a un dominio sin conexión.
Sintaxis
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
);
Parámetros
[in] lpDomain
Puntero a una cadena de caracteres terminada en NULL que especifica el nombre del dominio donde se crea la cuenta de equipo.
[in] lpMachineName
Puntero a una cadena de caracteres terminada en NULL que especifica el nombre corto de la máquina desde la que se deriva el atributo de cuenta de equipo sAMAccountName anexando "$". Este parámetro debe contener un nombre de equipo DNS o NetBIOS válido.
[in, optional] lpMachineAccountOU
Puntero opcional a una cadena de caracteres terminada en NULL que contiene el nombre de formato RFC 1779 de la unidad organizativa (OU) donde se creará la cuenta de equipo. Si especifica este parámetro, la cadena debe contener una ruta de acceso completa, por ejemplo, OU=testOU,DC=domain,DC=Domain,DC=com. De lo contrario, este parámetro debe ser NULL.
Si este parámetro es NULL, el contenedor de objetos de equipo conocido se usará como publicado en el dominio.
[in, optional] lpDcName
Puntero opcional a una cadena de caracteres terminada en NULL que contiene el nombre del controlador de dominio de destino.
[in] dwOptions
Conjunto de marcas de bits que definen las opciones de aprovisionamiento. Este parámetro puede ser uno o varios de los siguientes valores definidos en el archivo de encabezado Lmjoin.h .
| Valor | Significado |
|---|---|
|
Si el autor de la llamada requiere la creación de cuentas por privilegios, esta opción provocará un reintento en caso de error mediante funciones de creación de cuentas que permitan la interoperabilidad con controladores de dominio que se ejecutan en versiones anteriores de Windows.
El lpMachineAccountOU no se admite cuando se usa la compatibilidad con privilegios de nivel inferior. |
|
Si la cuenta con nombre ya existe, se intentará reutilizar la cuenta existente.
Esta opción requiere credenciales suficientes para esta operación (administrador de dominio o el propietario del objeto). |
|
Use la contraseña de la cuenta de máquina predeterminada, que es el nombre de la máquina en minúsculas. Esto es en gran medida para admitir el modelo de combinación no seguro anterior en el que la cuenta creada previamente suele usar esta contraseña predeterminada.
Nota Las aplicaciones deben evitar el uso de esta opción si es posible. Esta opción, así como la función NetJoinDomain con dwOptions establecida en NETSETUP_JOIN_UNSECURE para la combinación no segura solo se debe usar en versiones anteriores de Windows.
|
|
No intente encontrar la cuenta en ningún controlador de dominio del dominio. Esta opción hace que la operación sea más rápida, pero solo se debe usar cuando el autor de la llamada está seguro de que no se ha creado recientemente una cuenta con el mismo nombre.
Esta opción solo es válida cuando se especifica el parámetro lpDcName . Cuando se cumplen los requisitos previos, esta opción permite un aprovisionamiento más rápido útil para escenarios como el procesamiento por lotes. |
|
Esta opción recupera todos los certificados raíz de la entidad de certificación en el equipo local y los agrega al paquete de aprovisionamiento cuando no se proporcionan nombres de plantilla de certificado como parte del paquete de aprovisionamiento (el miembro aCertTemplateNames del struct de NETSETUP_PROVISIONING_PARAMS pasado en el parámetro pProvisioningParams a la función NetCreateProvisioningPackage es NULL).
Nota Esta marca solo es compatible con la función NetCreateProvisioningPackage en Windows 8, Windows Server 2012 y versiones posteriores.
|
[out, optional] pProvisionBinData
Puntero opcional que recibirá el blob binario opaco de metadatos serializados requeridos por la función NetRequestOfflineDomainJoin para completar una unión a un dominio sin conexión, si la función NetProvisionComputerAccount se completa correctamente. Los datos se devuelven como un búfer binario opaco que se puede pasar a la función NetRequestOfflineDomainJoin .
Si este parámetro es NULL, el parámetro pProvisionTextData no debe ser NULL. Si este parámetro no es NULL, el parámetro pProvisionTextData debe ser NULL.
[out, optional] pdwProvisionBinDataSize
Puntero a un valor que recibe el tamaño, en bytes, del búfer devuelto en el parámetro pProvisionBinData .
Este parámetro no debe ser NULL si el parámetro pProvisionBinData no es NULL. Este parámetro debe ser NULL cuando el parámetro pProvisionBinData es NULL.
[out, optional] pProvisionTextData
Puntero opcional que recibirá el blob binario opaco de metadatos serializados requeridos por la función NetRequestOfflineDomainJoin para completar una unión a un dominio sin conexión, si la función NetProvisionComputerAccount se completa correctamente. Los datos se devuelven en forma de cadena para insertarlos en un archivo de respuesta de instalación desatendida.
Si este parámetro es NULL, el parámetro pProvisionBinData no debe ser NULL. Si este parámetro no es NULL, el parámetro pProvisionBinData debe ser NULL.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es NERR_Success.
Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error o uno de los códigos de error del sistema.
| Código devuelto | Descripción |
|---|---|
|
Acceso denegado. Este error se devuelve si el autor de la llamada no tiene suficientes privilegios para completar la operación. |
|
Esta operación solo está disponible para el controlador de dominio principal del dominio. Este error se devuelve si se especificó un nombre de controlador de dominio en el parámetro lpDcName , pero el equipo especificado no se pudo validar como un controlador de dominio para el dominio de destino especificado en el parámetro lpDomain . |
|
Un parámetro es incorrecto. Este error se devuelve si el parámetro lpDomain o lpMachineName es NULL. Este error también se devuelve si los parámetros pProvisionBinData y pProvisionTextData son NULL. |
|
El dominio especificado no existía. |
|
No se admite la solicitud. Este error se devuelve si se especificó el parámetro lpMachineAccountOU y el controlador de dominio se ejecuta en una versión anterior de Windows que no admite este parámetro. |
|
El controlador de dominio especificado no cumple el requisito de versión de esta operación. |
|
Esta operación requiere un controlador de dominio que admita LDAP. |
|
La cuenta ya existe en el dominio y el bit de NETSETUP_PROVISION_REUSE_ACCOUNT no se especificó en el parámetro dwOptions . |
|
No se ha iniciado el servicio Workstation. |
|
Ya hay una llamada a procedimiento remoto en curso para este subproceso. |
|
No se admite la secuencia de protocolo de llamada a procedimiento remoto. |
Comentarios
La función NetProvisionComputerAccount es compatible con Windows 7 y Windows Server 2008 R2 para las operaciones de unión sin conexión. En Windows 8 o Windows Server 2008 R2, se recomienda usar la función NetCreateProvisioningPackage en lugar de la función NetProvisionComputerAccount.
La función NetProvisionComputerAccount se usa para aprovisionar una cuenta de equipo para su uso posterior en una operación de unión a un dominio sin conexión mediante la función NetRequestOfflineDomainJoin . El escenario de unión a un dominio sin conexión usa estas funciones de la siguiente manera:
- NetProvisionComputerAccount es una función de aprovisionamiento a la que se llama primero para realizar las operaciones de red necesarias para crear y configurar el objeto de equipo en Active Directory. La salida de NetProvisionComputerAccount es un blob binario opaco de metadatos serializados usados para el paso siguiente.
- A continuación, se llama a NetRequestOfflineDomainJoin, una función de inicialización de imagen, para insertar la salida de la función de aprovisionamiento NetProvisionComputerAccount en una imagen de sistema operativo Windows que se usará durante la instalación.
La función NetProvisionComputerAccount creará o reutilizará la cuenta de equipo en el dominio, recopilará todos los metadatos necesarios y los devolverá en un blob binario con versiones opacas o como texto para insertar en un archivo de respuesta de instalación desatendida. La operación de solicitud de unión a dominio sin conexión puede consumir el blob binario opaco que proporciona toda la entrada necesaria para completar la unión al dominio durante el primer arranque sin ninguna operación de red (solo actualizaciones de estado local).
Nota de seguridad: El blob devuelto por la función NetProvisionComputerAccount contiene datos muy confidenciales. Debe tratarse de forma tan segura como una contraseña de texto no cifrado. El blob contiene la contraseña de la cuenta de equipo y otra información sobre el dominio, incluido el nombre de dominio, el nombre de un controlador de dominio y el identificador de seguridad (SID) del dominio. Si el blob se transporta físicamente o a través de la red, se debe tener cuidado para transportarlo de forma segura. El diseño no hace ninguna disposición para proteger estos datos. Este problema existe hoy en día con archivos de respuesta de instalación desatendida que pueden llevar varios secretos, incluidas las contraseñas de usuario de dominio. El autor de la llamada debe proteger el blob y los archivos de instalación desatendidos. Las soluciones a este problema son variadas. Por ejemplo, se podría usar una clave intercambiada previamente para cifrar una sesión entre el consumidor y la entidad de aprovisionamiento, lo que permite una transferencia segura del blob opaco.
El blob opaco devuelto en el parámetro pProvisionBinData por la función NetProvisionComputerAccount tiene versiones para permitir escenarios de interoperabilidad y capacidad de servicio entre diferentes versiones de Windows (unión de cliente, máquina de aprovisionamiento y controlador de dominio). Actualmente, el escenario de combinación sin conexión no limita la duración del blob devuelto por la función NetProvisionComputerAccount .
Para las combinaciones de dominio sin conexión, la comprobación de acceso realizada depende de la configuración del dominio. La creación de cuentas de equipo está habilitada con tres métodos:
- Los administradores de dominio tienen derechos para crear cuentas de equipo.
- El SD en un contenedor puede delegar los derechos para crear cuentas de equipo.
- De forma predeterminada, los usuarios autenticados pueden crear cuentas de equipo con privilegios. Los usuarios autenticados se limitan a crear un número limitado de cuentas que se especifican como una cuota en el dominio (el valor predeterminado es 10). Para obtener más información, vea el atributo ms-DS-MachineAccountQuota en el esquema de Active Directory.
La función NetProvisionComputerAccount solo funciona con un controlador de dominio grabable y no funciona con un controlador de dominio de solo lectura. Una vez que el aprovisionamiento se realiza en un controlador de dominio grabable y la cuenta se replica en un controlador de dominio de solo lectura, las demás partes de la operación de unión a un dominio sin conexión no requieren acceso a un controlador de dominio.
Si la función NetProvisionComputerAccount se realiza correctamente, el puntero en el parámetro pProvisionBinData o pProvisionTextData (dependiendo de cuál era el parámetro no NULL) se devuelve con los datos serializados para su uso en una operación de combinación sin conexión o como texto en un archivo de instalación desatendido.
Para obtener más información sobre las operaciones de unión a un dominio sin conexión, consulte la Guía paso a paso de unión a un dominio sin conexión.
La unión (y desenlace) de un equipo a un dominio mediante NetJoinDomain y NetUnjoinDomain solo los puede realizar un miembro del grupo local Administradores en el equipo de destino. Tenga en cuenta que el administrador de dominio puede establecer requisitos adicionales para unir el dominio mediante la delegación y la asignación de privilegios.
Requisitos
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 R2 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | lmjoin.h (include Lm.h) |
| Library | Netapi32.lib |
| Archivo DLL | Netapi32.dll |
Consulte también
Funciones de administración de red
Introducción a la administración de redes
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de