NetProvisionComputerAccount 関数 (lmjoin.h)
NetProvisionComputerAccount 関数は、後でオフライン ドメイン参加操作で使用するためにコンピューター アカウントをプロビジョニングします。
構文
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
);
パラメーター
[in] lpDomain
コンピューター アカウントが作成されるドメインの名前を指定する NULL で終わる文字列へのポインター。
[in] lpMachineName
コンピューター アカウント属性 sAMAccountName が派生するコンピューターの短い名前を指定する NULL で終わる文字列へのポインター。'$' を追加します。 このパラメーターには、有効な DNS または NetBIOS コンピューター名を含める必要があります。
[in, optional] lpMachineAccountOU
コンピューター アカウントが作成される組織単位 (OU) の RFC 1779 形式名を含む NULL で終わる文字列への省略可能なポインター。 このパラメーターを指定する場合、文字列には、OU=testOU,DC=domain,DC=Domain,DC=com などの完全なパスが含まれている必要があります。 それ以外の場合、このパラメーターは NULL である必要があります。
このパラメーターが NULL の場合は、既知のコンピューター オブジェクト コンテナーがドメインで発行されたものとして使用されます。
[in, optional] lpDcName
ターゲットにするドメイン コントローラーの名前を含む NULL で終わる文字列への省略可能なポインター。
[in] dwOptions
プロビジョニング オプションを定義するビット フラグのセット。 このパラメーターには、 Lmjoin.h ヘッダー ファイルで定義されている次の値のうち 1 つ以上を指定できます。
| 値 | 意味 |
|---|---|
|
呼び出し元に特権によるアカウントの作成が必要な場合、このオプションでは、以前のバージョンの Windows で実行されているドメイン コントローラーとの相互運用性を可能にするアカウント作成関数を使用して、失敗時に再試行が発生します。
ダウンレベル特権のサポートを使用する場合、 lpMachineAccountOU はサポートされません。 |
|
名前付きアカウントが既に存在する場合は、既存のアカウントを再利用しようとします。
このオプションでは、この操作に十分な資格情報 (ドメイン管理者またはオブジェクト所有者) が必要です。 |
|
既定のマシン アカウント パスワードを使用します。これは、コンピューター名を小文字で指定します。 これは主に、事前に作成されたアカウントで通常この既定のパスワードが使用されている、以前の安全でない結合モデルをサポートするためです。
メモ 可能であれば、アプリケーションではこのオプションの使用を避ける必要があります。 このオプションと、安全でない結合のNETSETUP_JOIN_UNSECUREに dwOptions を設定した NetJoinDomain 関数は、以前のバージョンの Windows でのみ使用する必要があります。
|
|
ドメイン内のドメイン コントローラーでアカウントを検索しないでください。 このオプションを使用すると操作が高速になりますが、呼び出し元が同じ名前のアカウントが最近作成されていないことが確実な場合にのみ使用する必要があります。
このオプションは、 lpDcName パラメーターが指定されている場合にのみ有効です。 前提条件が満たされると、このオプションを使用すると、バッチ処理などのシナリオに役立つプロビジョニングを高速化する必要があります。 |
|
このオプションは、ローカル コンピューター上のすべてのルート証明機関証明書を取得し、プロビジョニング パッケージの一部として証明書テンプレート名が指定されていない場合にプロビジョニング パッケージに追加します (pProvisioningParams パラメーターで NetCreateProvisioningPackage 関数に渡されるNETSETUP_PROVISIONING_PARAMS構造体の aCertTemplateNames メンバーが NULL です)。
メモこのフラグは、Windows 8、Windows Server 2012、以降の NetCreateProvisioningPackage 関数でのみサポートされます。
|
[out, optional] pProvisionBinData
NetProvisionComputerAccount 関数が正常に完了した場合に、オフライン ドメイン参加を完了するために NetRequestOfflineDomainJoin 関数で必要なシリアル化されたメタデータの不透明なバイナリ BLOB を受け取るオプションのポインター。 データは、 NetRequestOfflineDomainJoin 関数に渡される可能性がある不透明なバイナリ バッファーとして返されます。
このパラメーターが NULL の場合、 pProvisionTextData パラメーターを NULL にすることはできません。 このパラメーターが NULL でない場合、 pProvisionTextData パラメーターは NULL である必要があります。
[out, optional] pdwProvisionBinDataSize
pProvisionBinData パラメーターで返されるバッファーのサイズをバイト単位で受け取る値へのポインター。
pProvisionBinData パラメーターが NULL でない場合は、このパラメーターを NULL にすることはできません。 pProvisionBinData パラメーターが NULL の場合、このパラメーターは NULL である必要があります。
[out, optional] pProvisionTextData
NetProvisionComputerAccount 関数が正常に完了した場合に、オフライン ドメイン参加を完了するために NetRequestOfflineDomainJoin 関数で必要なシリアル化されたメタデータの不透明なバイナリ BLOB を受け取るオプションのポインター。 無人セットアップ応答ファイルに埋め込む場合、データは文字列形式で返されます。
このパラメーターが NULL の場合、 pProvisionBinData パラメーターは NULL にすることはできません。 このパラメーターが NULL でない場合、 pProvisionBinData パラメーターは NULL である必要があります。
戻り値
関数が成功した場合、戻り値はNERR_Success。
関数が失敗した場合、戻り値には、次のいずれかのエラー コードまたは システム エラー コードのいずれかを指定できます。
| リターン コード | 説明 |
|---|---|
|
アクセスが拒否されました。 呼び出し元に操作を完了するための十分な特権がない場合、このエラーが返されます。 |
|
この操作は、ドメインのプライマリ ドメイン コントローラーに対してのみ許可されます。 このエラーは、 lpDcName パラメーターにドメイン コントローラー名が指定されていても、指定されたコンピューターを lpDomain パラメーターで指定されたターゲット ドメインのドメイン コントローラーとして検証できなかった場合に返されます。 |
|
パラメーターが正しくありません。 lpDomain または lpMachineName パラメーターが NULL の場合、このエラーが返されます。 このエラーは、pProvisionBinData パラメーターと pProvisionTextData パラメーターの両方が NULL の場合にも返されます。 |
|
指定されたドメインが存在しませんでした。 |
|
要求はサポートされていません。 lpMachineAccountOU パラメーターが指定されていて、このパラメーターをサポートしていない以前のバージョンの Windows でドメイン コントローラーが実行されている場合、このエラーが返されます。 |
|
指定したドメイン コントローラーがこの操作のバージョン要件を満たしていません。 |
|
この操作には、LDAP をサポートするドメイン コントローラーが必要です。 |
|
アカウントはドメインに既に存在し、 dwOptions パラメーターにNETSETUP_PROVISION_REUSE_ACCOUNT ビットが指定されていません。 |
|
ワークステーション サービスが開始されていません。 |
|
このスレッドでリモート プロシージャ コールが既に進行中です。 |
|
リモート プロシージャ コール プロトコル シーケンスはサポートされていません。 |
注釈
NetProvisionComputerAccount 関数は、オフライン参加操作で Windows 7 および Windows Server 2008 R2 でサポートされています。 Windows 8または Windows Server 2008 R2 では、NetProvisionComputerAccount 関数の代わりに NetCreateProvisioningPackage 関数を使用することをお勧めします。
NetProvisionComputerAccount 関数は、NetRequestOfflineDomainJoin 関数を使用して、オフライン ドメイン参加操作で後で使用するためにコンピューター アカウントをプロビジョニングするために使用されます。 オフライン ドメイン参加シナリオでは、次のようにこれらの関数を使用します。
- NetProvisionComputerAccount は、Active Directory でコンピューター オブジェクトを作成および構成するために必要なネットワーク操作を実行するために最初に呼び出されるプロビジョニング関数です。 NetProvisionComputerAccount からの出力は、次の手順で使用されるシリアル化されたメタデータの不透明なバイナリ BLOB です。
- その後、イメージ初期化関数である NetRequestOfflineDomainJoin が呼び出され、インストール時に使用される Windows オペレーティング システム イメージに NetProvisionComputerAccount プロビジョニング関数からの出力が挿入されます。
NetProvisionComputerAccount 関数は、ドメイン内のマシン アカウントを作成または再利用し、必要なすべてのメタデータを収集し、不透明なバージョン管理されたバイナリ BLOB で返すか、無人セットアップ応答ファイルに埋め込むためのテキストとして返します。 不透明なバイナリ BLOB は、オフライン ドメイン参加要求操作によって使用でき、ネットワーク操作なしで最初の起動時にドメイン参加を完了するために必要なすべての入力を提供します (ローカル状態の更新のみ)。
セキュリティに関する注意: NetProvisionComputerAccount 関数によって返される BLOB には、非常に機密性の高いデータが含まれています。 プレーンテキスト パスワードと同じように安全に扱う必要があります。 BLOB には、コンピューター アカウントのパスワードと、ドメイン名、ドメイン コントローラーの名前、ドメインのセキュリティ ID (SID) など、ドメインに関するその他の情報が含まれます。 BLOB が物理的またはネットワーク経由で転送されている場合は、安全に転送するように注意する必要があります。 この設計では、このデータをセキュリティで保護するためのプロビジョニングは行われません。 この問題は現在、ドメイン ユーザー パスワードを含む多くのシークレットを保持できる無人セットアップ応答ファイルに存在します。 呼び出し元は、BLOB と無人セットアップ ファイルをセキュリティで保護する必要があります。 この問題の解決策はさまざまです。 たとえば、事前に交換されたキーを使用して、コンシューマーとプロビジョニング エンティティの間のセッションを暗号化し、不透明な BLOB の安全な転送を可能にすることができます。
NetProvisionComputerAccount 関数によって pProvisionBinData パラメーターで返される不透明な BLOB は、さまざまなバージョンの Windows (クライアント、プロビジョニング マシン、ドメイン コントローラーの結合) 間の相互運用性とサービス性のシナリオを可能にするためにバージョン管理されています。 現在、オフライン参加シナリオでは、 NetProvisionComputerAccount 関数によって返される BLOB の有効期間は制限されていません。
オフライン ドメイン参加の場合、実行チェックアクセスはドメインの構成によって異なります。 コンピューター アカウントの作成は、次の 3 つの方法を使用して有効になります。
- ドメイン管理者には、コンピューター アカウントを作成する権限があります。
- コンテナー上の SD は、コンピューター アカウントを作成する権限を委任できます。
- 既定では、認証されたユーザーは特権によってコンピューター アカウントを作成できます。 認証されたユーザーは、ドメインのクォータとして指定されたアカウントの数に制限されます (既定値は 10)。 詳細については、Active Directory スキーマの ms-DS-MachineAccountQuota 属性を参照してください。
NetProvisionComputerAccount 関数は、書き込み可能なドメイン コントローラーでのみ機能し、読み取り専用ドメイン コントローラーに対して機能しません。 書き込み可能なドメイン コントローラーに対してプロビジョニングが行われ、アカウントが読み取り専用ドメイン コントローラーにレプリケートされると、オフライン ドメイン参加操作の他の部分ではドメイン コントローラーへのアクセスは必要ありません。
NetProvisionComputerAccount 関数が成功した場合、pProvisionBinData パラメーターまたは pProvisionTextData パラメーター内のポインター (パラメーターが NULL でなかったかどうかに応じて) が、オフライン結合操作で使用するか、無人セットアップ ファイルのテキストとしてシリアル化されたデータと共に返されます。
オフライン ドメイン参加操作の詳細については、「 オフライン ドメイン参加のステップ バイ ステップ ガイド」を参照してください。
NetJoinDomain と NetUnjoinDomain を使用したドメインへのコンピューターの参加 (および参加解除) は、ターゲット コンピューター上の Administrators ローカル グループのメンバーのみが実行できます。 ドメイン管理者は、委任と特権の割り当てを使用してドメインに参加するための追加要件を設定できることに注意してください。
要件
| サポートされている最小のクライアント | Windows 7 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 R2 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | lmjoin.h (include Lm.h) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |