Share via

NetCreateProvisioningPackage 関数 (lmjoin.h)

  • [アーティクル]

NetCreateProvisioningPackage 関数は、後でオフライン ドメイン参加操作で使用するためにコンピューター アカウントをプロビジョニングするプロビジョニング パッケージを作成します。 パッケージには、プロビジョニング中にマシンに追加する証明書とポリシーに関する情報が含まれている場合もあります。

構文

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

パラメーター

[in] pProvisioningParams

プロビジョニング パッケージに関する情報を含む NETSETUP_PROVISIONING_PARAMS 構造体へのポインター。

この構造体のメンバーには、次の値が定義されています。

値 意味
dwVersion
 プロビジョニング パッケージ内の Windows のバージョン。 このメンバーは、 Lmjoin.h ヘッダー ファイルで定義されている次の値を使用する必要があります。

NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain
 コンピューター アカウントが作成されるドメインの名前を指定する、null で終わる定数文字列へのポインター。
lpMachineName
 コンピューター アカウント属性 sAMAccountName の派生元となるコンピューターの短い名前を指定する、null で終わる定数文字列へのポインター。'$' を追加します。 このパラメーターには、有効な DNS または NetBIOS コンピューター名を含める必要があります。
lpMachineAccountOU
 コンピューター アカウントが作成される組織単位 (OU) の RFC 1779 形式名を含む、null で終わる定数文字列への省略可能なポインター。 このパラメーターを指定する場合、文字列には、OU=testOU,DC=domain,DC=Domain,DC=com などの完全なパスが含まれている必要があります。 それ以外の場合、このパラメーターは NULL である必要があります。

このパラメーターが NULL の場合は、既知のコンピューター オブジェクト コンテナーがドメインで発行されたものとして使用されます。
lpDcName
 ターゲットとするドメイン コントローラーの名前を含む、null で終わる定数文字列への省略可能なポインター。
dwProvisionOptions
 プロビジョニング オプションを定義するビット フラグのセット。 このパラメーターには、NetProvisionComputerAccount 関数に渡される dwOptions パラメーターに指定された値を 1 つ以上指定できます。

これらの可能な値は、 Lmjoin.h ヘッダー ファイルで定義されます。

NETSETUP_PROVISION_ROOT_CA_CERTS オプションは、Windows 8とWindows Server 2012でのみサポートされます。
aCertTemplateNames
 NULL で終わる証明書テンプレート名の配列への省略可能なポインター。
cCertTemplateNames
 aCertTemplateNames が NULL でない場合、このメンバーは配列内の項目数の明示的なカウントを提供します。
aMachinePolicyNames
 NULL で終わるコンピューター ポリシー名の配列への省略可能なポインター。
cMachinePolicyNames
 aMachinePolicyNames が NULL でない場合、このメンバーは配列内の項目数の明示的なカウントを提供します。
aMachinePolicyPaths
 文字列の配列への省略可能なポインター。 各配列要素は、レジストリ ポリシー ファイル形式のファイルへの完全パスまたは部分パスを指定する NULL で終わる文字列です。 レジストリ ポリシー ファイル形式の詳細については、「レジストリ ポリシー ファイル形式」を参照してください。

パスには、リモート サーバー上の UNC パスを指定できます。
cMachinePolicyPaths
 aMachinePolicyPaths が NULL でない場合、このメンバーは配列内の項目数の明示的なカウントを提供します。

[out, optional] ppPackageBinData

NetProvisionComputerAccount 関数が正常に完了した場合に、オフライン ドメイン参加を完了するために NetRequestOfflineDomainJoin 関数に必要なパッケージを受け取る省略可能なポインター。 データは、 NetRequestOfflineDomainJoin 関数に渡される可能性がある不透明なバイナリ バッファーとして返されます。

このパラメーターが NULL の場合、 pPackageTextData パラメーターは NULL にすることはできません。 このパラメーターが NULL でない場合、 pPackageTextData パラメーターは NULL である必要があります。

[out, optional] pdwPackageBinDataSize

pProvisionBinData パラメーターで返されるバッファーのサイズをバイト単位で受け取る値へのポインター。

pPackageBinData パラメーターが NULL でない場合は、このパラメーターを NULL にすることはできません。 pPackageBinData パラメーターが NULL の場合、このパラメーターは NULL である必要があります。

[out, optional] ppPackageTextData

NetProvisionComputerAccount 関数が正常に完了した場合に、オフライン ドメイン参加を完了するために NetRequestOfflineDomainJoin 関数に必要なパッケージを受け取る省略可能なポインター。 無人セットアップ応答ファイルに埋め込む場合、データは文字列形式で返されます。

このパラメーターが NULL の場合、 pPackageBinData パラメーターは NULL にすることはできません。 このパラメーターが NULL でない場合、 pPackageBinData パラメーターは NULL である必要があります。

戻り値

関数が成功した場合、戻り値はNERR_Success。

関数が失敗した場合、戻り値には、次のいずれかのエラー コードまたは システム エラー コードのいずれかを指定できます。

リターン コード 説明
ERROR_ACCESS_DENIED
 アクセスが拒否されました。 呼び出し元に操作を完了するための十分な特権がない場合、このエラーが返されます。
ERROR_INVALID_DOMAIN_ROLE
 この操作は、ドメインのプライマリ ドメイン コントローラーに対してのみ許可されます。 このエラーは、pProvisioningParams パラメーターが指すNETSETUP_PROVISIONING_PARAMS構造体の lpDcName にドメイン コントローラー名が指定されているが、指定されたコンピューターが、NETSETUP_PROVISIONING_PARAMSの lpDomain で指定されたターゲット ドメインのドメイン コントローラーとして検証できなかった場合に返されます。
ERROR_INVALID_PARAMETER
 パラメーターが正しくありません。 このエラーは、 両方の pProvisioningParams パラメーターが NULL の場合にも返されます。 このエラーは、pProvisioningParams パラメーターが指すNETSETUP_PROVISIONING_PARAMS構造体の lpDomain または lpMachineName メンバーが NULL の場合にも返されます。
ERROR_NO_SUCH_DOMAIN
 指定されたドメインが存在しませんでした。
ERROR_NOT_SUPPORTED
 要求はサポートされていません。 このエラーは、pProvisioningParams パラメーターが指すNETSETUP_PROVISIONING_PARAMS構造体で lpMachineAccountOU メンバーが指定されており、ドメイン コントローラーがこのパラメーターをサポートしていない以前のバージョンの Windows で実行されている場合に返されます。
NERR_DS8DCRequired
 指定したドメイン コントローラーがこの操作のバージョン要件を満たしていません。
NERR_LDAPCapableDCRequired
 この操作には、LDAP をサポートするドメイン コントローラーが必要です。
NERR_UserExists
 アカウントはドメインに既に存在し、pProvisioningParams パラメーターが指すNETSETUP_PROVISIONING_PARAMS構造体の dwProvisionOptions メンバーにNETSETUP_PROVISION_REUSE_ACCOUNT ビットが指定されていません。
NERR_WkstaNotStarted
 ワークステーション サービスが開始されていません。
RPC_S_CALL_IN_PROGRESS
 このスレッドでリモート プロシージャ コールが既に進行中です。
RPC_S_PROTSEQ_NOT_SUPPORTED
 リモート プロシージャ コール プロトコル シーケンスはサポートされていません。

注釈

NetCreateProvisioningPackage 関数は、オフライン結合操作のWindows 8とWindows Server 2012でサポートされています。 Windows 7 の場合は、 NetProvisionComputerAccount 関数を 使用します。

NetCreateProvisioningPackage 関数は、NetRequestProvisioningPackageInstall 関数を使用して、オフライン ドメイン参加操作で後で使用するためにコンピューター アカウントをプロビジョニングするために使用されます。

オフライン ドメイン参加シナリオでは、次の 2 つの関数を使用します。

  • NetCreateProvisioningPackage は、Active Directory でコンピューター オブジェクトを作成および構成するために必要なネットワーク操作を実行するために最初に呼び出されるプロビジョニング関数です。 NetCreateProvisioningPackage からの出力は、次の手順で使用されるパッケージです。
  • イメージ初期化関数である NetRequestProvisioningPackageInstall が呼び出され、インストール前とインストール後に使用するために、NetCreateProvisioningPackage プロビジョニング関数からの出力が Windows オペレーティング システム イメージに挿入されます。
Windows 初期化コードを変更すると、この保存された状態が検出され、ドメイン参加のローカル専用部分に影響します。

pPackageBinData ポインターと pdwPackageBinDataSize out ポインターを使用する場合は、pPackageTextData out ポインターを NULL に設定します。 pPackageTextData を使用する場合は、pPackageBinData ポインターと pdwPackageBinDataSize out ポインターを NULL に設定します。

pProvisioningParams パラメーターは、プロビジョニング パッケージに含めるデータを指定します。 パッケージには、ドメイン参加に関連する情報が含まれており、コンピューターにインストールするポリシーと証明書に関する情報を含めることもできます。 プロビジョニング パッケージは、次の 4 つの方法で使用できます。

  • ドメイン参加
  • 証明書のドメイン参加とインストール
  • ドメイン参加とポリシーのインストール
  • 証明書とポリシーのドメイン参加とインストール

NetCreateProvisioningPackage 関数は、ドメイン内のマシン アカウントを作成または再利用し、必要なすべてのメタデータを収集してパッケージで返します。 パッケージは、オフライン ドメイン参加要求操作で使用できます。この操作では、ネットワーク操作なしで最初のブート中にドメイン参加を完了するために必要なすべての入力を指定できます (ローカル状態の更新のみ)。

セキュリティに関する注意: NetCreateProvisioningPackage 関数によって返されるパッケージには、非常に機密性の高いデータが含まれています。 プレーンテキスト パスワードと同じように安全に扱う必要があります。 パッケージには、コンピューター アカウントのパスワードと、ドメイン名、ドメイン コントローラーの名前、ドメインのセキュリティ ID (SID) など、ドメインに関するその他の情報が含まれています。 パッケージが物理的またはネットワーク経由で転送されている場合は、安全に転送するように注意する必要があります。 この設計では、このデータをセキュリティで保護するためのプロビジョニングは行われません。 この問題は現在、ドメイン ユーザー パスワードを含む多くのシークレットを保持できる無人セットアップ応答ファイルに存在します。 呼び出し元はパッケージをセキュリティで保護する必要があります。 この問題の解決策はさまざまです。 たとえば、事前に交換されたキーを使用して、コンシューマーとプロビジョニング エンティティの間のセッションを暗号化し、パッケージの安全な転送を可能にすることができます。

NetCreateProvisioningPackage 関数によって pPackageBinData パラメーターで返されるパッケージは、さまざまなバージョンの Windows (クライアントへの参加、マシンのプロビジョニング、ドメイン コントローラーの使用など) 間の相互運用性とサービス性のシナリオを可能にするためにバージョン管理されています。 Windows 8またはWindows Server 2012で作成されたパッケージは、Windows 7 または Windows Server 2008 R2 を使用できますが、ドメイン参加情報のみが有効になります (証明書とポリシーはサポートされていません)。 現在、オフライン結合シナリオでは、 NetCreateProvisioningPackage 関数によって返されるパッケージの有効期間は制限されていません。

オフライン ドメイン参加の場合、実行チェックアクセスはドメインの構成によって異なります。 コンピューター アカウントの作成は、次の 3 つの方法を使用して有効になります。

  • ドメイン管理者には、コンピューター アカウントを作成する権限があります。
  • コンテナー上の SD は、コンピューター アカウントを作成する権限を委任できます。
  • 既定では、認証されたユーザーは特権によってコンピューター アカウントを作成できます。 認証されたユーザーは、ドメインのクォータとして指定されたアカウントの数に制限されます (既定値は 10)。 詳細については、Active Directory スキーマの ms-DS-MachineAccountQuota 属性を参照してください。

NetCreateProvisioningPackage 関数は、書き込み可能なドメイン コントローラーでのみ機能し、読み取り専用ドメイン コントローラーに対して機能しません。 書き込み可能なドメイン コントローラーに対してプロビジョニングが行われ、アカウントが読み取り専用ドメイン コントローラーにレプリケートされると、オフライン ドメイン参加操作の他の部分ではドメイン コントローラーへのアクセスは必要ありません。

NetCreateProvisioningPackage 関数が成功した場合、pPackageBinData パラメーターまたは pPackageTextData パラメーター (NULL ではないパラメーターに応じて) のポインターが、シリアル化されたデータと共に返され、オフライン結合操作で使用するか、無人セットアップ ファイル内のテキストとして使用されます。

プロビジョニング プロセスのすべてのフェーズは、ローカル コンピューター上の NetSetup.log ファイルに追加されます。 プロビジョニング プロセスには、プロビジョニング パッケージが作成されるコンピューター、パッケージのインストールを要求するコンピューター、パッケージがインストールされているコンピューターの 3 つの異なるコンピューターを含めることができます。 実行 NetSetup.log操作 に従って、3 台のコンピューターすべてにファイル情報が格納されます。 これらのファイルの内容を確認することは、オンラインとオフラインのプロビジョニング エラーをトラブルシューティングする最も一般的な方法です。 管理者が実行したプロビジョニング操作は、%WINDIR%\Debug のNetSetup.log ファイルに記録されます。 管理者以外が実行したプロビジョニング操作は、%USERPROFILE%\Debug フォルダー内のNetSetup.log ファイルに記録されます。

オフライン ドメイン参加操作の詳細については、「 オフライン ドメイン参加のステップ バイ ステップ ガイド」を参照してください。

NetJoinDomain と NetUnjoinDomain を使用したドメインへのコンピューターの参加 (および参加解除) は、ターゲット コンピューターの Administrators ローカル グループのメンバーによってのみ実行されます。 ドメイン管理者は、委任と特権の割り当てを使用してドメインに参加するための追加要件を設定できることに注意してください。

要件

   
サポートされている最小のクライアント Windows 8 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2012 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー lmjoin.h (include Lm.h)
Library Netapi32.lib
[DLL] Netapi32.dll

こちらもご覧ください

NETSETUP_PROVISIONING_PARAMS

NetJoinDomain

NetRenameMachineInDomain

NetRequestOfflineDomainJoin

NetRequestProvisioningPackageInstall

NetUnjoinDomain

ネットワーク管理機能

ネットワーク管理の概要