NetProvisionComputerAccount-Funktion (lmjoin.h)
Die NetProvisionComputerAccount-Funktion stellt ein Computerkonto zur späteren Verwendung in einem Offlinedomänenbeitritt bereit.
Syntax
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
);
Parameter
[in] lpDomain
Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen der Domäne angibt, in der das Computerkonto erstellt wird.
[in] lpMachineName
Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den Kurznamen des Computers angibt, von dem das Computerkonto-Attribut sAMAccountName durch Anfügen eines "$" abgeleitet wird. Dieser Parameter muss einen gültigen DNS- oder NetBIOS-Computernamen enthalten.
[in, optional] lpMachineAccountOU
Ein optionaler Zeiger auf eine NULL-endende Zeichenfolge, die den RFC 1779-Formatnamen der Organisationseinheit (OU) enthält, in der das Computerkonto erstellt wird. Wenn Sie diesen Parameter angeben, muss die Zeichenfolge einen vollständigen Pfad enthalten, z. B. OU=testOU,DC=domain,DC=Domain,DC=com. Andernfalls muss dieser Parameter NULL sein.
Wenn dieser Parameter NULL ist, wird der bekannte Computerobjektcontainer wie in der Domäne veröffentlicht verwendet.
[in, optional] lpDcName
Ein optionaler Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des Domänencontrollers für das Ziel enthält.
[in] dwOptions
Eine Reihe von Bitflags, die Bereitstellungsoptionen definieren. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln, die in der Lmjoin.h-Headerdatei definiert sind.
| Wert | Bedeutung |
|---|---|
|
Wenn der Aufrufer die Kontoerstellung nach Berechtigungen erfordert, führt diese Option zu einem Wiederholungsfehler mithilfe von Kontoerstellungsfunktionen, die die Interoperabilität mit Domänencontrollern ermöglichen, die unter früheren Versionen von Windows ausgeführt werden.
Die lpMachineAccountOU wird nicht unterstützt, wenn Unterstützung für Downlevel-Berechtigungen verwendet wird. |
|
Wenn das benannte Konto bereits vorhanden ist, wird versucht, das vorhandene Konto wiederzuverwenden.
Diese Option erfordert ausreichende Anmeldeinformationen für diesen Vorgang (Domänenadministrator oder Objektbesitzer). |
|
Verwenden Sie das Standardkennwort für das Computerkonto, bei dem es sich um den Computernamen in Kleinbuchstaben handelt. Dies dient größtenteils der Unterstützung des älteren unsicheren Joinmodells, bei dem das vorab erstellte Konto in der Regel dieses Standardkennwort verwendet.
Hinweis Anwendungen sollten diese Option nach Möglichkeit vermeiden. Diese Option sowie die NetJoinDomain-Funktion mit dwOptions, die auf NETSETUP_JOIN_UNSECURE für unsichere Verknüpfungen festgelegt ist, sollten nur in früheren Versionen von Windows verwendet werden.
|
|
Versuchen Sie nicht, das Konto auf einem Domänencontroller in der Domäne zu finden. Diese Option beschleunigt den Vorgang, sollte aber nur verwendet werden, wenn der Aufrufer sicher ist, dass vor kurzem kein Konto mit demselben Namen erstellt wurde.
Diese Option ist nur gültig, wenn der lpDcName-Parameter angegeben ist. Wenn die Voraussetzungen erfüllt sind, ermöglicht diese Option eine schnellere Bereitstellung, die für Szenarien wie die Batchverarbeitung nützlich ist. |
|
Diese Option ruft alle Stammzertifikate der Zertifizierungsstelle auf dem lokalen Computer ab und fügt sie dem Bereitstellungspaket hinzu, wenn keine Zertifikatvorlagennamen als Teil des Bereitstellungspakets bereitgestellt werden (das aCertTemplateNames-Element der NETSETUP_PROVISIONING_PARAMS Struktur, die im pProvisioningParams-Parameter an die NetCreateProvisioningPackage-Funktion übergeben wird, ist NULL).
Hinweis Dieses Flag wird nur von der NetCreateProvisioningPackage-Funktion auf Windows 8, Windows Server 2012 und höher unterstützt.
|
[out, optional] pProvisionBinData
Ein optionaler Zeiger, der das undurchsichtige binäre Blob der serialisierten Metadaten empfängt, die für die NetRequestOfflineDomainJoin-Funktion erforderlich sind, um einen Offlinedomänenbeitritt abzuschließen, wenn die NetProvisionComputerAccount-Funktion erfolgreich abgeschlossen wird. Die Daten werden als undurchsichtiger binärer Puffer zurückgegeben, der an die NetRequestOfflineDomainJoin-Funktion übergeben werden kann.
Wenn dieser Parameter NULL ist, darf der pProvisionTextData-Parameter nicht NULL sein. Wenn dieser Parameter nicht NULL ist, muss der pProvisionTextData-ParameterNULL sein.
[out, optional] pdwProvisionBinDataSize
Ein Zeiger auf einen Wert, der die Größe des Puffers in Bytes empfängt, der im Parameter pProvisionBinData zurückgegeben wird.
Dieser Parameter darf nicht NULL sein, wenn der Parameter pProvisionBinData nicht NULL ist. Dieser Parameter muss NULL sein, wenn der pProvisionBinData-ParameterNULL ist.
[out, optional] pProvisionTextData
Ein optionaler Zeiger, der das undurchsichtige binäre Blob der serialisierten Metadaten empfängt, die für die NetRequestOfflineDomainJoin-Funktion erforderlich sind, um einen Offlinedomänenbeitritt abzuschließen, wenn die NetProvisionComputerAccount-Funktion erfolgreich abgeschlossen wird. Die Daten werden in Zeichenfolgenform zum Einbetten in eine Unbeaufsichtigte Setupantwortdatei zurückgegeben.
Wenn dieser Parameter NULL ist, darf der pProvisionBinData-Parameter nicht NULL sein. Wenn dieser Parameter nicht NULL ist, muss der pProvisionBinData-ParameterNULL sein.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes oder einer der Systemfehlercodes sein.
| Rückgabecode | Beschreibung |
|---|---|
|
Zugriff verweigert.“ Dieser Fehler wird zurückgegeben, wenn der Aufrufer nicht über ausreichende Berechtigungen zum Abschließen des Vorgangs verfügt. |
|
Dieser Vorgang ist nur für den primären Domänencontroller der Domäne zulässig. Dieser Fehler wird zurückgegeben, wenn im lpDcName-Parameter ein Domänencontrollername angegeben wurde, der angegebene Computer jedoch nicht als Domänencontroller für die im lpDomain-Parameter angegebene Zieldomäne überprüft werden konnte. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der LpDomain - oder lpMachineName-ParameterNULL ist. Dieser Fehler wird auch zurückgegeben, wenn sowohl die Parameter pProvisionBinData als auch pProvisionTextDataNULL sind. |
|
Die angegebene Domäne war nicht vorhanden. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der lpMachineAccountOU-Parameter angegeben wurde und der Domänencontroller unter einer früheren Version von Windows ausgeführt wird, die diesen Parameter nicht unterstützt. |
|
Der angegebene Domänencontroller erfüllt nicht die Versionsanforderung für diesen Vorgang. |
|
Für diesen Vorgang ist ein Domänencontroller erforderlich, der LDAP unterstützt. |
|
Das Konto ist bereits in der Domäne vorhanden, und das NETSETUP_PROVISION_REUSE_ACCOUNT Bit wurde nicht im dwOptions-Parameter angegeben. |
|
Der Arbeitsstationsdienst wurde nicht gestartet. |
|
Für diesen Thread wird bereits ein Remoteprozeduraufruf ausgeführt. |
|
Die Protokollsequenz des Remoteprozeduraufrufs wird nicht unterstützt. |
Hinweise
Die NetProvisionComputerAccount-Funktion wird unter Windows 7 und Windows Server 2008 R2 für Offlinebeitrittsvorgänge unterstützt. Unter Windows 8 oder Windows Server 2008 R2 wird empfohlen, die NetCreateProvisioningPackage-Funktion anstelle der NetProvisionComputerAccount-Funktion zu verwenden.
Die NetProvisionComputerAccount-Funktion wird verwendet, um mithilfe der NetRequestOfflineDomainJoin-Funktion ein Computerkonto zur späteren Verwendung in einem Offlinedomänenbeitritt bereitzustellen. Das Szenario für den Offlinedomänenbeitritt verwendet die folgenden Funktionen:
- NetProvisionComputerAccount ist eine Bereitstellungsfunktion, die zuerst aufgerufen wird, um die Netzwerkvorgänge auszuführen, die zum Erstellen und Konfigurieren des Computerobjekts in Active Directory erforderlich sind. Die Ausgabe von NetProvisionComputerAccount ist ein undurchsichtiges binäres Blob serialisierter Metadaten, das für den nächsten Schritt verwendet wird.
- NetRequestOfflineDomainJoin, eine Imageinitialisierungsfunktion, wird dann aufgerufen, um die Ausgabe der NetProvisionComputerAccount-Bereitstellungsfunktion in ein Windows-Betriebssystemimage einzufügen, das während der Installation verwendet werden soll.
Die NetProvisionComputerAccount-Funktion erstellt oder verwendet das Computerkonto in der Domäne, sammelt alle erforderlichen Metadaten und gibt es in einem binären Blob mit undurchsichtiger Version oder als Text zum Einbetten in eine Unbeaufsichtigte Setupantwortdatei zurück. Das undurchsichtige binäre Blob kann vom Anforderungsvorgang für den Offlinedomänenbeitritt verwendet werden, der alle erforderlichen Eingaben für den Domänenbeitritt während des ersten Starts ohne Netzwerkvorgänge (nur aktualisierungen des lokalen Zustands) liefert.
Sicherheitshinweis: Das von der NetProvisionComputerAccount-Funktion zurückgegebene Blob enthält sehr vertrauliche Daten. Es sollte genauso sicher behandelt werden wie ein Klartextkennwort. Das Blob enthält das Computerkontokennwort und andere Informationen zur Domäne, einschließlich des Domänennamens, des Namens eines Domänencontrollers und der Sicherheits-ID (SID) der Domäne. Wenn das Blob physisch oder über das Netzwerk transportiert wird, muss darauf geachtet werden, dass es sicher transportiert wird. Der Entwurf sieht keine Vorkehrungen für die Sicherung dieser Daten vor. Dieses Problem tritt heute bei Unbeaufsichtigten Setupantwortdateien auf, die eine Reihe von Geheimnissen enthalten können, einschließlich Domänenbenutzerkennwörtern. Der Aufrufer muss das Blob und die Unbeaufsichtigten Setupdateien schützen. Die Lösungen für dieses Problem sind vielfältig. Beispielsweise könnte ein vorab ausgetauschter Schlüssel verwendet werden, um eine Sitzung zwischen dem Consumer und der Bereitstellungsentität zu verschlüsseln, was eine sichere Übertragung des undurchsichtigen Blobs ermöglicht.
Das undurchsichtige Blob, das im pProvisionBinData-Parameter von der NetProvisionComputerAccount-Funktion zurückgegeben wird, ist versioniert, um Interoperabilitäts- und Betriebsfähigkeitsszenarien zwischen verschiedenen Versionen von Windows (Verbinden von Client, Bereitstellungscomputer und Domänencontroller) zu ermöglichen. Das Offlinebeitrittsszenario begrenzt derzeit nicht die Lebensdauer des Blobs, das von der NetProvisionComputerAccount-Funktion zurückgegeben wird.
Bei Offlinedomänenbeitritten hängt die durchgeführte Zugriffsüberprüfung von der Konfiguration der Domäne ab. Die Computerkontoerstellung wird mithilfe von drei Methoden aktiviert:
- Domänenadministratoren verfügen über Rechte zum Erstellen von Computerkonten.
- Die SD in einem Container kann die Rechte zum Erstellen von Computerkonten delegieren.
- Standardmäßig können authentifizierte Benutzer Computerkonten nach Berechtigungen erstellen. Authentifizierte Benutzer sind auf das Erstellen einer begrenzten Anzahl von Konten beschränkt, die als Kontingent für die Domäne angegeben werden (der Standardwert ist 10). Weitere Informationen finden Sie unter dem Attribut ms-DS-MachineAccountQuota im Active Directory-Schema.
Die NetProvisionComputerAccount-Funktion funktioniert nur mit einem beschreibbaren Domänencontroller und nicht mit einem schreibgeschützten Domänencontroller. Sobald die Bereitstellung für einen beschreibbaren Domänencontroller erfolgt und das Konto auf einen schreibgeschützten Domänencontroller repliziert wird, ist für die anderen Teile des Offlinedomänenbeitritts kein Zugriff auf einen Domänencontroller erforderlich.
Wenn die NetProvisionComputerAccount-Funktion erfolgreich ist, wird der Zeiger im pProvisionBinData - oder pProvisionTextData-Parameter (je nachdem, welcher Parameter nicht NULL war) mit den serialisierten Daten zur Verwendung in einem Offlineeinbindungsvorgang oder als Text in einer unbeaufsichtigten Setupdatei zurückgegeben.
Weitere Informationen zu Offline-Domänenbeitrittsvorgängen finden Sie in der Schritt-für-Schritt-Anleitung zum Offlinedomänenbeitritt.
Das Verknüpfen (und Aufheben der Verknüpfung) eines Computers mit einer Domäne mithilfe von NetJoinDomain und NetUnjoinDomain kann nur von einem Mitglied der lokalen Gruppe Administratoren auf dem Zielcomputer ausgeführt werden. Beachten Sie, dass der Domänenadministrator zusätzliche Anforderungen für den Domänenbeitritt durch Delegierung und Zuweisung von Berechtigungen festlegen kann.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 7 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 R2 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | lmjoin.h (lm.h einschließen) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |
Weitere Informationen
Übersicht über die Netzwerkverwaltung