Funzione NetProvisionComputerAccount (lmjoin.h)
La funzione NetProvisionComputerAccount effettua il provisioning di un account computer per un uso successivo in un'operazione di aggiunta a un dominio offline.
Sintassi
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
);
Parametri
[in] lpDomain
Puntatore a una stringa di caratteri con terminazione NULL che specifica il nome del dominio in cui viene creato l'account computer.
[in] lpMachineName
Puntatore a una stringa di caratteri con terminazione NULL che specifica il nome breve del computer da cui deriva l'attributo dell'account computer sAMAccountName aggiungendo un valore '$'. Questo parametro deve contenere un nome di computer DNS o NetBIOS valido.
[in, optional] lpMachineAccountOU
Puntatore facoltativo a una stringa di caratteri con terminazione NULL contenente il nome di formato RFC 1779 dell'unità organizzativa in cui verrà creato l'account computer. Se si specifica questo parametro, la stringa deve contenere un percorso completo, ad esempio OU=testOU,DC=domain,DC=Domain,DC=com. In caso contrario, questo parametro deve essere NULL.
Se questo parametro è NULL, il contenitore di oggetti computer noto verrà usato come pubblicato nel dominio.
[in, optional] lpDcName
Puntatore facoltativo a una stringa di caratteri con terminazione NULL contenente il nome del controller di dominio di destinazione.
[in] dwOptions
Set di flag di bit che definiscono le opzioni di provisioning. Questo parametro può essere uno o più dei valori seguenti definiti nel file di intestazione Lmjoin.h .
| Valore | Significato |
|---|---|
|
Se il chiamante richiede la creazione dell'account tramite privilegio, questa opzione causerà un nuovo tentativo in caso di errore usando le funzioni di creazione dell'account che consentono l'interoperabilità con i controller di dominio in esecuzione nelle versioni precedenti di Windows.
LpMachineAccountOU non è supportato quando si usa il supporto dei privilegi di livello inferiore. |
|
Se l'account denominato esiste già, verrà effettuato un tentativo di riutilizzare l'account esistente.
Questa opzione richiede credenziali sufficienti per questa operazione (amministratore di dominio o proprietario dell'oggetto). |
|
Usare la password dell'account computer predefinita, ovvero il nome del computer in lettere minuscole. Questo è in gran parte per supportare il modello di join non sicuro precedente in cui l'account creato in genere usava questa password predefinita.
Nota Se possibile, le applicazioni devono evitare di usare questa opzione. Questa opzione e la funzione NetJoinDomain con dwOptions impostata su NETSETUP_JOIN_UNSECURE per l'aggiunta non sicura devono essere usate solo nelle versioni precedenti di Windows.
|
|
Non tentare di trovare l'account in alcun controller di dominio nel dominio. Questa opzione rende l'operazione più veloce, ma deve essere usata solo quando il chiamante è certo che un account con lo stesso nome non sia stato creato di recente.
Questa opzione è valida solo quando viene specificato il parametro lpDcName . Quando vengono soddisfatti i prerequisiti, questa opzione consente il provisioning più rapido utile per scenari come l'elaborazione batch. |
|
Questa opzione recupera tutti i certificati dell'autorità di certificazione radice nel computer locale e li aggiunge al pacchetto di provisioning quando non vengono forniti nomi di modello di certificato come parte del pacchetto di provisioning (il membro aCertTemplateNames dello struct NETSETUP_PROVISIONING_PARAMS passato nel parametro pProvisioningParams alla funzione NetCreateProvisioningPackage è NULL).
Nota Questo flag è supportato solo dalla funzione NetCreateProvisioningPackage in Windows 8, Windows Server 2012 e versioni successive.
|
[out, optional] pProvisionBinData
Puntatore facoltativo che riceverà il BLOB binario opaco dei metadati serializzati richiesti dalla funzione NetRequestOfflineDomainJoin per completare un aggiunta a un dominio offline, se la funzione NetProvisionComputerAccount viene completata correttamente. I dati vengono restituiti come buffer binario opaco che può essere passato alla funzione NetRequestOfflineDomainJoin .
Se questo parametro è NULL, il parametro pProvisionTextData non deve essere NULL. Se questo parametro non è NULL, il parametro pProvisionTextData deve essere NULL.
[out, optional] pdwProvisionBinDataSize
Puntatore a un valore che riceve le dimensioni, in byte, del buffer restituito nel parametro pProvisionBinData .
Questo parametro non deve essere NULL se il parametro pProvisionBinData non è NULL. Questo parametro deve essere NULL quando il parametro pProvisionBinData è NULL.
[out, optional] pProvisionTextData
Puntatore facoltativo che riceverà il BLOB binario opaco dei metadati serializzati richiesti dalla funzione NetRequestOfflineDomainJoin per completare un aggiunta a un dominio offline, se la funzione NetProvisionComputerAccount viene completata correttamente. I dati vengono restituiti in formato stringa per l'incorporamento in un file di risposte di installazione automatica.
Se questo parametro è NULL, il parametro pProvisionBinData non deve essere NULL. Se questo parametro non è NULL, il parametro pProvisionBinData deve essere NULL.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NERR_Success.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti o uno dei codici di errore di sistema seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Accesso negato. Questo errore viene restituito se il chiamante non dispone di privilegi sufficienti per completare l'operazione. |
|
Questa operazione è consentita solo per il controller di dominio primario del dominio. Questo errore viene restituito se nel parametro lpDcName è stato specificato un nome di controller di dominio, ma non è stato possibile convalidare il computer specificato come controller di dominio per il dominio di destinazione specificato nel parametro lpDomain . |
|
Un parametro non è corretto. Questo errore viene restituito se il parametro lpDomain o lpMachineName è NULL. Questo errore viene restituito anche se i parametri pProvisionBinData e pProvisionTextData sono NULL. |
|
Il dominio specificato non esiste. |
|
La richiesta non è supportata. Questo errore viene restituito se il parametro lpMachineAccountOU è stato specificato e il controller di dominio è in esecuzione in una versione precedente di Windows che non supporta questo parametro. |
|
Il controller di dominio specificato non soddisfa il requisito di versione per questa operazione. |
|
Questa operazione richiede un controller di dominio che supporta LDAP. |
|
L'account esiste già nel dominio e il bit NETSETUP_PROVISION_REUSE_ACCOUNT non è stato specificato nel parametro dwOptions . |
|
Il servizio Workstation non è stato avviato. |
|
Una chiamata di procedura remota è già in corso per questo thread. |
|
La sequenza di protocollo di chiamata di procedura remota non è supportata. |
Commenti
La funzione NetProvisionComputerAccount è supportata in Windows 7 e Windows Server 2008 R2 per le operazioni di join offline. In Windows 8 o Windows Server 2008 R2 è consigliabile usare la funzione NetCreateProvisioningPackage anziché la funzione NetProvisionComputerAccount.
La funzione NetProvisionComputerAccount viene usata per effettuare il provisioning di un account computer per usarlo successivamente in un'operazione di aggiunta a un dominio offline tramite la funzione NetRequestOfflineDomainJoin . Lo scenario di aggiunta a un dominio offline usa queste funzioni come indicato di seguito:
- NetProvisionComputerAccount è una funzione di provisioning che viene prima chiamata per eseguire le operazioni di rete necessarie per creare e configurare l'oggetto computer in Active Directory. L'output di NetProvisionComputerAccount è un BLOB binario opaco di metadati serializzati usati per il passaggio successivo.
- NetRequestOfflineDomainJoin, una funzione di inizializzazione dell'immagine, viene quindi chiamata per inserire l'output dalla funzione di provisioning NetProvisionComputerAccount in un'immagine del sistema operativo Windows da usare durante l'installazione.
La funzione NetProvisionComputerAccount creerà o riutilizzerà l'account del computer nel dominio, raccoglierà tutti i metadati necessari e lo restituirà in un BLOB binario opaco con versione o come testo per l'incorporamento in un file di risposte di installazione automatica. Il BLOB binario opaco può essere utilizzato dall'operazione di richiesta di aggiunta al dominio offline fornendo tutto l'input necessario per completare l'aggiunta al dominio durante il primo avvio senza alcuna operazione di rete (solo aggiornamenti dello stato locale).
Nota sulla sicurezza: Il BLOB restituito dalla funzione NetProvisionComputerAccount contiene dati molto sensibili. Deve essere trattato in modo sicuro come una password di testo non crittografato. Il BLOB contiene la password dell'account computer e altre informazioni sul dominio, tra cui il nome di dominio, il nome di un controller di dominio e l'ID di sicurezza (SID) del dominio. Se il BLOB viene trasportato fisicamente o in rete, è necessario prestare attenzione al trasporto sicuro. La progettazione non effettua alcun provisioning per proteggere questi dati. Questo problema esiste oggi con i file di risposta automatica che possono contenere diversi segreti, tra cui password utente di dominio. Il chiamante deve proteggere il BLOB e i file di installazione automatica. Le soluzioni a questo problema sono diverse. Ad esempio, una chiave pre-scambiata può essere usata per crittografare una sessione tra il consumer e l'entità di provisioning che consente un trasferimento sicuro del BLOB opaco.
Il BLOB opaco restituito nel parametro pProvisionBinData dalla funzione NetProvisionComputerAccount viene versioneta per consentire scenari di interoperabilità e di servizio tra versioni diverse di Windows (aggiunta di client, provisioning del computer e controller di dominio). Lo scenario di join offline attualmente non limita la durata del BLOB restituito dalla funzione NetProvisionComputerAccount .
Per i join di dominio offline, il controllo di accesso eseguito dipende dalla configurazione del dominio. La creazione dell'account computer è abilitata usando tre metodi:
- Gli amministratori di dominio hanno diritti per creare account computer.
- L'SD in un contenitore può delegare i diritti per creare account computer.
- Per impostazione predefinita, gli utenti autenticati possono creare account computer per privilegio. Gli utenti autenticati sono limitati alla creazione di un numero limitato di account specificati come quota nel dominio (il valore predefinito è 10). Per altre informazioni, vedere l'attributo ms-DS-MachineAccountQuota nello schema di Active Directory.
La funzione NetProvisionComputerAccount funziona solo con un controller di dominio scrivibile e non funziona su un controller di dominio di sola lettura. Una volta eseguito il provisioning su un controller di dominio scrivibile e l'account viene replicato in un controller di dominio di sola lettura, le altre parti dell'operazione di aggiunta al dominio offline non richiedono l'accesso a un controller di dominio.
Se la funzione NetProvisionComputerAccount ha esito positivo, il puntatore nel parametro pProvisionBinData o pProvisionTextData (a seconda del parametro non null) viene restituito con i dati serializzati da usare in un'operazione di join offline o come testo in un file di installazione automatica.
Per altre informazioni sulle operazioni di aggiunta al dominio offline, vedere la Guida dettagliata all'aggiunta al dominio offline.
L'aggiunta (e l'annullamento della partecipazione) di un computer a un dominio tramite NetJoinDomain e NetUnjoinDomain può essere eseguita solo da un membro del gruppo locale Administrators nel computer di destinazione. Si noti che l'amministratore del dominio può impostare requisiti aggiuntivi per l'aggiunta al dominio usando la delega e l'assegnazione dei privilegi.
Requisiti
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | lmjoin.h (include Lm.h) |
| Libreria | Netapi32.lib |
| DLL | Netapi32.dll |
Vedi anche
Funzioni di gestione della rete
Panoramica sulla gestione della rete