NetProvisionComputerAccount, fonction (lmjoin.h)

Article
08/24/2023

La fonction NetProvisionComputerAccount provisionne un compte d’ordinateur pour une utilisation ultérieure dans une opération de jointure de domaine hors connexion.

Syntaxe

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

Paramètres

[in] lpDomain

Pointeur vers une chaîne de caractères terminée par NULL qui spécifie le nom du domaine dans lequel le compte d’ordinateur est créé.

[in] lpMachineName

Pointeur vers une chaîne de caractères terminée par NULL qui spécifie le nom court de l’ordinateur à partir duquel l’attribut de compte d’ordinateur sAMAccountName est dérivé en ajoutant un « $ ». Ce paramètre doit contenir un nom de machine DNS ou NetBIOS valide.

[in, optional] lpMachineAccountOU

Pointeur facultatif vers une chaîne de caractères terminée par null qui contient le nom de format RFC 1779 de l’unité d’organisation (UO) dans laquelle le compte d’ordinateur sera créé. Si vous spécifiez ce paramètre, la chaîne doit contenir un chemin d’accès complet, par exemple, OU=testOU,DC=domain,DC=domain,DC=com. Sinon, ce paramètre doit être NULL.

Si ce paramètre a la valeur NULL, le conteneur d’objets ordinateur bien connu est utilisé comme publié dans le domaine.

[in, optional] lpDcName

Pointeur facultatif vers une chaîne de caractères terminée par NULL qui contient le nom du contrôleur de domaine à cibler.

[in] dwOptions

Ensemble d’indicateurs de bits qui définissent les options d’approvisionnement. Ce paramètre peut être une ou plusieurs des valeurs suivantes définies dans le fichier d’en-tête Lmjoin.h .

Valeur	Signification
NETSETUP_PROVISION_DOWNLEVEL_PRIV_SUPPORT 0x00000001	Si l’appelant nécessite la création d’un compte par privilège, cette option entraîne une nouvelle tentative en cas d’échec à l’aide de fonctions de création de compte permettant l’interopérabilité avec les contrôleurs de domaine exécutés sur des versions antérieures de Windows. LpMachineAccountOU n’est pas pris en charge lors de l’utilisation de la prise en charge des privilèges de niveau inférieur.
NETSETUP_PROVISION_REUSE_ACCOUNT 0x00000002	Si le compte nommé existe déjà, une tentative est effectuée pour réutiliser le compte existant. Cette option nécessite des informations d’identification suffisantes pour cette opération (administrateur de domaine ou propriétaire de l’objet).
NETSETUP_PROVISION_USE_DEFAULT_PASSWORD 0x00000004	Utilisez le mot de passe du compte d’ordinateur par défaut, qui est le nom de la machine en minuscules. Il s’agit en grande partie de prendre en charge l’ancien modèle de jointure non sécurisée où le compte précréé utilisait généralement ce mot de passe par défaut. Note Les applications doivent éviter d’utiliser cette option si possible. Cette option ainsi que la fonction NetJoinDomain avec dwOptions défini sur NETSETUP_JOIN_UNSECURE pour la jointure non sécurisée ne doivent être utilisés que sur les versions antérieures de Windows.
NETSETUP_PROVISION_SKIP_ACCOUNT_SEARCH 0x00000008	N’essayez pas de trouver le compte sur un contrôleur de domaine dans le domaine. Cette option accélère l’opération, mais ne doit être utilisée que lorsque l’appelant est certain qu’un compte portant le même nom n’a pas été créé récemment. Cette option n’est valide que lorsque le paramètre lpDcName est spécifié. Lorsque les conditions préalables sont remplies, cette option permet un provisionnement plus rapide, utile pour des scénarios tels que le traitement par lots.
NETSETUP_PROVISION_ROOT_CA_CERTS 0x00000010	Cette option récupère tous les certificats d’autorité de certification racine sur l’ordinateur local et les ajoute au package d’approvisionnement lorsqu’aucun nom de modèle de certificat n’est fourni dans le cadre du package d’approvisionnement (le membre aCertTemplateNames du struct NETSETUP_PROVISIONING_PARAMS passé dans le paramètre pProvisioningParams à la fonction NetCreateProvisioningPackage est NULL). Note Cet indicateur est uniquement pris en charge par la fonction NetCreateProvisioningPackage sur Windows 8, Windows Server 2012 et versions ultérieures.

[out, optional] pProvisionBinData

Pointeur facultatif qui recevra l’objet blob binaire opaque de métadonnées sérialisées requises par la fonction NetRequestOfflineDomainJoin pour terminer une jointure de domaine hors connexion, si la fonction NetProvisionComputerAccount se termine correctement. Les données sont retournées sous la forme d’une mémoire tampon binaire opaque qui peut être passée à la fonction NetRequestOfflineDomainJoin .

Si ce paramètre a la valeur NULL, le paramètre pProvisionTextData ne doit pas être NULL. Si ce paramètre n’est pas NULL, le paramètre pProvisionTextData doit être NULL.

[out, optional] pdwProvisionBinDataSize

Pointeur vers une valeur qui reçoit la taille, en octets, de la mémoire tampon retournée dans le paramètre pProvisionBinData .

Ce paramètre ne doit pas être NULL si le paramètre pProvisionBinData n’est pas NULL. Ce paramètre doit être NULL lorsque le paramètre pProvisionBinData a la valeur NULL.

[out, optional] pProvisionTextData

Pointeur facultatif qui recevra l’objet blob binaire opaque de métadonnées sérialisées requises par la fonction NetRequestOfflineDomainJoin pour terminer une jointure de domaine hors connexion, si la fonction NetProvisionComputerAccount se termine correctement. Les données sont retournées sous forme de chaîne pour l’incorporation dans un fichier de réponses d’installation sans assistance.

Si ce paramètre a la valeur NULL, le paramètre pProvisionBinData ne doit pas être NULL. Si ce paramètre n’est pas NULL, le paramètre pProvisionBinData doit être NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants ou l’un des codes d’erreur système.

Code de retour	Description
ERROR_ACCESS_DENIED	L’accès est refusé. Cette erreur est retournée si l’appelant ne dispose pas des privilèges suffisants pour terminer l’opération.
ERROR_INVALID_DOMAIN_ROLE	Cette opération n’est autorisée que pour le contrôleur de domaine principal du domaine. Cette erreur est retournée si un nom de contrôleur de domaine a été spécifié dans le paramètre lpDcName , mais que l’ordinateur spécifié n’a pas pu être validé en tant que contrôleur de domaine pour le domaine cible spécifié dans le paramètre lpDomain .
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si le paramètre lpDomain ou lpMachineName a la valeur NULL. Cette erreur est également retournée si les paramètres pProvisionBinData et pProvisionTextData ont la valeur NULL.
ERROR_NO_SUCH_DOMAIN	Le domaine spécifié n’existait pas.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si le paramètre lpMachineAccountOU a été spécifié et que le contrôleur de domaine s’exécute sur une version antérieure de Windows qui ne prend pas en charge ce paramètre.
NERR_DS8DCRequired	Le contrôleur de domaine spécifié ne répond pas aux exigences de version pour cette opération.
NERR_LDAPCapableDCRequired	Cette opération nécessite un contrôleur de domaine qui prend en charge LDAP.
NERR_UserExists	Le compte existe déjà dans le domaine et le bit NETSETUP_PROVISION_REUSE_ACCOUNT n’a pas été spécifié dans le paramètre dwOptions .
NERR_WkstaNotStarted	Le service Station de travail n’a pas été démarré.
RPC_S_CALL_IN_PROGRESS	Un appel de procédure distante est déjà en cours pour ce thread.
RPC_S_PROTSEQ_NOT_SUPPORTED	La séquence de protocole d’appel de procédure distante n’est pas prise en charge.

Remarques

La fonction NetProvisionComputerAccount est prise en charge sur Windows 7 et Windows Server 2008 R2 pour les opérations de jointure hors connexion. Sur Windows 8 ou Windows Server 2008 R2, il est recommandé d’utiliser la fonction NetCreateProvisioningPackage à la place de la fonction NetProvisionComputerAccount.

La fonction NetProvisionComputerAccount permet d’approvisionner un compte d’ordinateur en vue d’une utilisation ultérieure dans une opération de jointure de domaine hors connexion à l’aide de la fonction NetRequestOfflineDomainJoin . Le scénario de jonction de domaine hors connexion utilise ces fonctions comme suit :

NetProvisionComputerAccount est une fonction d’approvisionnement qui est d’abord appelée pour effectuer les opérations réseau nécessaires à la création et à la configuration de l’objet ordinateur dans Active Directory. La sortie de NetProvisionComputerAccount est un objet blob binaire opaque de métadonnées sérialisées utilisées pour l’étape suivante.
NetRequestOfflineDomainJoin, une fonction d’initialisation d’image, est ensuite appelée pour injecter la sortie de la fonction d’approvisionnement NetProvisionComputerAccount dans une image de système d’exploitation Windows à utiliser lors de l’installation.

Les modifications apportées au code d’initialisation Windows détectent cet état enregistré et affectent la partie locale uniquement de la jonction de domaine.

La fonction NetProvisionComputerAccount crée ou réutilise le compte d’ordinateur dans le domaine, collecte toutes les métadonnées nécessaires et les retourne dans un objet blob binaire avec version opaque ou sous forme de texte pour l’incorporation dans un fichier de réponses d’installation sans assistance. L’objet blob binaire opaque peut être consommé par l’opération de demande de jonction de domaine hors connexion fournissant toutes les entrées nécessaires pour terminer la jonction de domaine lors du premier démarrage sans aucune opération réseau (mises à jour d’état locales uniquement).

Note de sécurité : L’objet blob retourné par la fonction NetProvisionComputerAccount contient des données très sensibles. Il doit être traité de manière aussi sécurisée qu’un mot de passe en texte clair. L’objet blob contient le mot de passe du compte d’ordinateur et d’autres informations sur le domaine, notamment le nom de domaine, le nom d’un contrôleur de domaine et l’ID de sécurité (SID) du domaine. Si l’objet blob est transporté physiquement ou sur le réseau, vous devez veiller à le transporter en toute sécurité. La conception ne prévoit aucune disposition pour la sécurisation de ces données. Ce problème existe aujourd’hui avec les fichiers de réponses d’installation sans assistance qui peuvent contenir un certain nombre de secrets, y compris les mots de passe utilisateur du domaine. L’appelant doit sécuriser l’objet blob et les fichiers d’installation sans assistance. Les solutions à ce problème sont variées. Par exemple, une clé pré-échangée peut être utilisée pour chiffrer une session entre le consommateur et l’entité d’approvisionnement, ce qui permet un transfert sécurisé de l’objet blob opaque.

L’objet blob opaque retourné dans le paramètre pProvisionBinData par la fonction NetProvisionComputerAccount est versionné pour permettre des scénarios d’interopérabilité et de facilité de service entre différentes versions de Windows (jointure du client, machine d’approvisionnement et contrôleur de domaine). Actuellement, le scénario de jointure hors connexion ne limite pas la durée de vie de l’objet blob retourné par la fonction NetProvisionComputerAccount .

Pour les jointures de domaine hors connexion, l’accès case activée effectué dépend de la configuration du domaine. La création de compte d’ordinateur est activée à l’aide de trois méthodes :

Les administrateurs de domaine disposent des droits nécessaires pour créer des comptes d’ordinateur.
Le SD sur un conteneur peut déléguer les droits de création de comptes d’ordinateur.
Par défaut, les utilisateurs authentifiés peuvent créer des comptes d’ordinateur par privilège. Les utilisateurs authentifiés sont limités à la création d’un nombre limité de comptes spécifiés sous la forme d’un quota sur le domaine (la valeur par défaut est 10). Pour plus d’informations, consultez l’attribut ms-DS-MachineAccountQuota dans le schéma Active Directory.

La fonction NetProvisionComputerAccount fonctionne uniquement avec un contrôleur de domaine accessible en écriture et ne fonctionne pas sur un contrôleur de domaine en lecture seule. Une fois que l’approvisionnement est effectué sur un contrôleur de domaine accessible en écriture et que le compte est répliqué sur un contrôleur de domaine en lecture seule, les autres parties de l’opération de jonction de domaine hors connexion n’ont pas besoin d’accéder à un contrôleur de domaine.

Si la fonction NetProvisionComputerAccount réussit, le pointeur dans le paramètre pProvisionBinData ou pProvisionTextData (selon que le paramètre was n’était pas NULL) est retourné avec les données sérialisées pour une utilisation dans une opération de jointure hors connexion ou en tant que texte dans un fichier d’installation sans assistance.

Pour plus d’informations sur les opérations de jointure de domaine hors connexion, consultez le Guide pas à pas de la jonction de domaine hors connexion.

La jonction (et la disjoination) d’un ordinateur à un domaine à l’aide de NetJoinDomain et NetUnjoinDomain ne peuvent être effectuées que par un membre du groupe local Administrateurs sur l’ordinateur cible. Notez que l’administrateur de domaine peut définir des exigences supplémentaires pour joindre le domaine à l’aide de la délégation et de l’attribution de privilèges.

Configuration requise


Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmjoin.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll