NetCreateProvisioningPackage, fonction (lmjoin.h)

Article
08/24/2023

La fonction NetCreateProvisioningPackage crée un package d’approvisionnement qui provisionne un compte d’ordinateur pour une utilisation ultérieure dans une opération de jointure de domaine hors connexion. Le package peut également contenir des informations sur les certificats et les stratégies à ajouter à l’ordinateur lors de l’approvisionnement.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
  [in]            PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
  [out, optional] PBYTE                         *ppPackageBinData,
  [out, optional] DWORD                         *pdwPackageBinDataSize,
  [out, optional] LPWSTR                        *ppPackageTextData
);

Paramètres

[in] pProvisioningParams

Pointeur vers une structure NETSETUP_PROVISIONING_PARAMS qui contient des informations sur le package d’approvisionnement.

Les valeurs suivantes sont définies pour les membres de cette structure :

Valeur	Signification
dwVersion	Version de Windows dans le package d’approvisionnement. Ce membre doit utiliser la valeur suivante définie dans le fichier d’en-tête Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain	Pointeur vers une chaîne de caractères constante terminée par une valeur Null qui spécifie le nom du domaine dans lequel le compte d’ordinateur est créé.
lpMachineName	Pointeur vers une chaîne de caractères constante 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.
lpMachineAccountOU	Pointeur facultatif vers une chaîne de caractères constante terminée par null qui contient le nom de format RFC 1779 de l’unité d’organisation (UO) où 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.
lpDcName	Pointeur facultatif vers une chaîne de caractères constante terminée par un caractère null qui contient le nom du contrôleur de domaine à cibler.
dwProvisionOptions	Ensemble d’indicateurs de bits qui définissent les options d’approvisionnement. Ce paramètre peut être une ou plusieurs des valeurs spécifiées pour le paramètre dwOptions passé à la fonction NetProvisionComputerAccount . Ces valeurs possibles sont définies dans le fichier d’en-tête Lmjoin.h . L’option NETSETUP_PROVISION_ROOT_CA_CERTS est uniquement prise en charge sur Windows 8 et Windows Server 2012.
aCertTemplateNames	Pointeur facultatif vers un tableau de noms de modèle de certificat terminés par NULL.
cCertTemplateNames	Quand aCertTemplateNames n’a pas la valeur NULL, ce membre fournit un nombre explicite du nombre d’éléments dans le tableau.
aMachinePolicyNames	Pointeur facultatif vers un tableau de noms de stratégie d’ordinateur terminés par NULL.
cMachinePolicyNames	Quand aMachinePolicyNames n’a pas la valeur NULL, ce membre fournit un nombre explicite du nombre d’éléments dans le tableau.
aMachinePolicyPaths	Pointeur facultatif vers un tableau de chaînes de caractères. Chaque élément de tableau est une chaîne de caractères terminée par NULL qui spécifie le chemin d’accès complet ou partiel à un fichier au format fichier de stratégie du Registre. Pour plus d’informations sur le format de fichier de stratégie du Registre, consultez Format de fichier de stratégie du Registre. Le chemin d’accès peut être un chemin UNC sur un serveur distant.
cMachinePolicyPaths	Lorsqu’aMachinePolicyPaths n’a pas la valeur NULL, ce membre fournit un nombre explicite du nombre d’éléments dans le tableau.

[out, optional] ppPackageBinData

Pointeur facultatif qui recevra le package requis 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 pPackageTextData ne doit pas être NULL. Si ce paramètre n’est pas NULL, le paramètre pPackageTextData doit être NULL.

[out, optional] pdwPackageBinDataSize

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 pPackageBinData n’est pas NULL. Ce paramètre doit être NULL lorsque le paramètre pPackageBinData a la valeur NULL.

[out, optional] ppPackageTextData

Pointeur facultatif qui recevra le package requis 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 pPackageBinData ne doit pas être NULL. Si ce paramètre n’est pas NULL, le paramètre pPackageBinData 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 lpDcName du struct NETSETUP_PROVISIONING_PARAMS pointé par le paramètre pProvisioningParams , 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 lpDomain du NETSETUP_PROVISIONING_PARAMS.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est également retournée si le paramètre pProvisioningParams a la valeur NULL. Cette erreur est également retournée si le membre lpDomain ou lpMachineName du struct NETSETUP_PROVISIONING_PARAMS pointé par le paramètre pProvisioningParams est 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 membre lpMachineAccountOU a été spécifié dans le struct NETSETUP_PROVISIONING_PARAMS pointé par le paramètre pProvisioningParams 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 membre dwProvisionOptions du struct NETSETUP_PROVISIONING_PARAMS pointé vers le paramètre pProvisioningParams .
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 NetCreateProvisioningPackage est prise en charge sur Windows 8 et Windows Server 2012 pour les opérations de jointure hors connexion. Pour Windows 7, utilisez la fonction NetProvisionComputerAccount .

La fonction NetCreateProvisioningPackage 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 NetRequestProvisioningPackageInstall .

Le scénario de jonction de domaine hors connexion utilise deux fonctions :

NetCreateProvisioningPackage 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 NetCreateProvisioningPackage est un package utilisé pour l’étape suivante.
NetRequestProvisioningPackageInstall, une fonction d’initialisation d’image, est appelée pour injecter la sortie de la fonction d’approvisionnement NetCreateProvisioningPackage dans une image de système d’exploitation Windows à utiliser pendant la préinstallation et la post-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.

Lorsque les pointeurs de sortie pPackageBinData et pdwPackageBinDataSize sont utilisés, définissez le pointeur de sortie pPackageTextData sur NULL. Lorsque pPackageTextData est utilisé, définissez les pointeurs de sortie pPackageBinData et pdwPackageBinDataSize sur NULL.

Le paramètre pProvisioningParams spécifie les données à inclure dans le package d’approvisionnement. Le package inclut des informations relatives à la jonction de domaine, ainsi que des informations sur les stratégies et les certificats à installer sur l’ordinateur. Le package d’approvisionnement peut être utilisé de quatre façons :

Jonction de domaine
Jonction de domaine et installation de certificats
Jonction de domaine et installation de stratégies
Jonction de domaine et installation de certificats et de stratégies

La fonction NetCreateProvisioningPackage 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 package. Le package peut être consommé par l’opération de demande de jonction de domaine hors connexion qui fournit 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 de l’état local uniquement).

Note de sécurité : Le package retourné par la fonction NetCreateProvisioningPackage 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. Le package 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 le package est transporté physiquement ou sur le réseau, il faut 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 le package. 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é du package.

Le package retourné dans le paramètre pPackageBinData par la fonction NetCreateProvisioningPackage est versionné pour permettre des scénarios d’interopérabilité et de facilité de service entre différentes versions de Windows (par exemple, la jonction d’un client, l’approvisionnement d’une machine et l’utilisation d’un contrôleur de domaine). Un package créé sur Windows 8 ou Windows Server 2012 peut être utilisé sous Windows 7 ou Windows Server 2008 R2, mais seules les informations de jointure de domaine prendront effet (les certificats et les stratégies ne sont pas pris en charge). Actuellement, le scénario de jointure hors connexion ne limite pas la durée de vie du package retourné par la fonction NetCreateProvisioningPackage .

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 NetCreateProvisioningPackage 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 ne nécessitent pas d’accès à un contrôleur de domaine.

Si la fonction NetCreateProvisioningPackage réussit, le pointeur dans le paramètre pPackageBinData ou pPackageTextData (selon le paramètre qui 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.

Toutes les phases du processus d’approvisionnement s’ajoutent à un fichier NetSetup.log sur l’ordinateur local. Le processus d’approvisionnement peut inclure jusqu’à trois ordinateurs différents : l’ordinateur où le package d’approvisionnement est créé, l’ordinateur qui demande l’installation du package et l’ordinateur sur lequel le package est installé. Il y aura NetSetup.log informations de fichier stockées sur les trois ordinateurs en fonction de l’opération effectuée. L’examen du contenu de ces fichiers est le moyen le plus courant de résoudre les erreurs d’approvisionnement en ligne et hors connexion. Les opérations d’approvisionnement entreprises par les administrateurs sont enregistrées dans le fichier NetSetup.log dans %WINDIR%\Debug. Les opérations d’approvisionnement effectuées par des non-administrateurs sont enregistrées dans le fichier NetSetup.log dans le dossier %USERPROFILE%\Debug .

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 jointure (et la disjoination) d’un ordinateur à un domaine à l’aide de NetJoinDomain et NetUnjoinDomain est effectuée uniquement 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 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmjoin.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll