NetCreateProvisioningPackage 함수(lmjoin.h)

아티클
03/14/2023

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 매개 변수에 지정된 값 중 하나 이상일 수 있습니다. 이러한 가능한 값은 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_PARAMSlpDomain에 지정된 대상 도메인의 도메인 컨트롤러로 유효성을 검사할 수 없는 경우 반환됩니다.
ERROR_INVALID_PARAMETER	매개 변수가 잘못되었습니다. pProvisioningParams 매개 변수가 모두 NULL인 경우에도 이 오류가 반환됩니다. pProvisioningParams 매개 변수가 가리키는 NETSETUP_PROVISIONING_PARAMS 구조체의 lpDomain 또는 lpMachineName 멤버가 NULL인 경우에도 이 오류가 반환됩니다.
ERROR_NO_SUCH_DOMAIN	지정한 도메인이 없습니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 lpMachineAccountOU 멤버가 pProvisioningParams 매개 변수가 가리키는 NETSETUP_PROVISIONING_PARAMS 구조체에 지정되었고 도메인 컨트롤러가 이 매개 변수를 지원하지 않는 이전 버전의 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 함수를 사용하여 오프라인 도메인 조인 작업에서 나중에 사용할 컴퓨터 계정을 프로비전하는 데 사용됩니다.

오프라인 도메인 조인 시나리오에서는 다음 두 가지 함수를 사용합니다.

NetCreateProvisioningPackage 는 Active Directory에서 컴퓨터 개체를 만들고 구성하는 데 필요한 네트워크 작업을 수행하기 위해 먼저 호출되는 프로비저닝 함수입니다. NetCreateProvisioningPackage의 출력은 다음 단계에서 사용되는 패키지입니다.
이미지 초기화 함수인 NetRequestProvisioningPackageInstall은 설치 전 및 설치 후 사용할 Windows 운영 체제 이미지에 NetCreateProvisioningPackage 프로비저닝 함수의 출력을 삽입하기 위해 호출됩니다.

Windows 초기화 코드를 변경하면 이 저장된 상태를 검색하고 도메인 조인의 로컬 전용 부분에 영향을 미칩니다.

pPackageBinData 및 pdwPackageBinDataSize 포인터를 사용하는 경우 pPackageTextData out 포인터를 NULL로 설정합니다. pPackageTextData를 사용하는 경우 pPackageBinData 및 pdwPackageBinDataSize 포인터를 NULL로 설정합니다.

pProvisioningParams 매개 변수는 프로비저닝 패키지에 포함할 데이터를 지정합니다. 패키지에는 도메인 가입과 관련된 정보가 포함되며 컴퓨터에 설치할 정책 및 인증서에 대한 정보도 포함될 수 있습니다. 프로비저닝 패키지는 다음 네 가지 방법으로 사용할 수 있습니다.

도메인 가입
도메인 가입 및 인증서 설치
도메인 가입 및 정책 설치
인증서 및 정책의 도메인 가입 및 설치

NetCreateProvisioningPackage 함수는 도메인에서 컴퓨터 계정을 만들거나 다시 사용하고, 필요한 모든 메타데이터를 수집하고, 패키지에 반환합니다. 패키지는 네트워크 작업 없이 첫 번째 부팅 중에 도메인 조인을 완료하는 데 필요한 모든 입력을 제공하는 오프라인 도메인 조인 요청 작업에서 사용할 수 있습니다(로컬 상태 업데이트만 해당).

보안 참고 사항: NetCreateProvisioningPackage 함수에서 반환된 패키지에는 매우 중요한 데이터가 포함되어 있습니다. 일반 텍스트 암호처럼 안전하게 처리해야 합니다. 패키지에는 도메인 이름, 도메인 컨트롤러 이름 및 도메인의 SID(보안 ID)를 포함하여 컴퓨터 계정 암호 및 도메인에 대한 기타 정보가 포함됩니다. 패키지를 물리적으로 또는 네트워크를 통해 전송하는 경우 안전하게 전송하려면 주의해야 합니다. 디자인에서는 이 데이터를 보호하기 위한 프로비저닝을 수행하지 않습니다. 이 문제는 도메인 사용자 암호를 포함하여 많은 비밀을 전달할 수 있는 무인 설정 응답 파일에서 현재 존재합니다. 호출자는 패키지를 보호해야 합니다. 이 문제에 대한 해결 방법은 다양합니다. 예를 들어 미리 교환된 키를 사용하여 소비자와 프로비전 엔터티 간의 세션을 암호화하여 패키지를 안전하게 전송할 수 있습니다.

NetCreateProvisioningPackage 함수에 의해 pPackageBinData 매개 변수에 반환된 패키지는 클라이언트 조인, 컴퓨터 프로비전 및 도메인 컨트롤러 사용과 같은 다양한 버전의 Windows 간의 상호 운용성 및 서비스 가능성 시나리오를 허용하도록 버전이 지정됩니다. Windows 8 또는 Windows Server 2012 만든 패키지는 Windows 7 또는 Windows Server 2008 R2를 사용할 수 있지만 도메인 가입 정보만 적용됩니다(인증서 및 정책은 지원되지 않음). 오프라인 조인 시나리오는 현재 NetCreateProvisioningPackage 함수에서 반환하는 패키지의 수명을 제한하지 않습니다.

오프라인 도메인 조인의 경우 수행되는 액세스 검사 도메인의 구성에 따라 달라집니다. 컴퓨터 계정 만들기는 다음 세 가지 방법을 사용하여 사용하도록 설정됩니다.

도메인 관리자는 컴퓨터 계정을 만들 권한이 있습니다.
컨테이너의 SD는 컴퓨터 계정을 만들 수 있는 권한을 위임할 수 있습니다.
기본적으로 인증된 사용자는 권한으로 컴퓨터 계정을 만들 수 있습니다. 인증된 사용자는 도메인에서 할당량으로 지정된 제한된 수의 계정을 만드는 것으로 제한됩니다(기본값은 10). 자세한 내용은 Active Directory 스키마의 ms-DS-MachineAccountQuota 특성을 참조하세요.

NetCreateProvisioningPackage 함수는 쓰기 가능한 도메인 컨트롤러에서만 작동하며 읽기 전용 도메인 컨트롤러에 대해 작동하지 않습니다. 쓰기 가능한 도메인 컨트롤러에 대해 프로비전이 수행되고 계정이 읽기 전용 도메인 컨트롤러에 복제되면 오프라인 도메인 조인 작업의 다른 부분에서는 도메인 컨트롤러에 액세스할 필요가 없습니다.

NetCreateProvisioningPackage 함수가 성공하면 pPackageBinData 또는 pPackageTextData 매개 변수(NULL이 아닌 매개 변수에 따라)의 포인터가 오프라인 조인 작업에 사용하거나 무인 설치 파일의 텍스트로 사용할 직렬화된 데이터와 함께 반환됩니다.

프로비전 프로세스의 모든 단계는 로컬 컴퓨터의 NetSetup.log 파일에 추가됩니다. 프로비저닝 프로세스에는 프로비전 패키지가 만들어진 컴퓨터, 패키지 설치를 요청하는 컴퓨터 및 패키지가 설치된 컴퓨터 등 최대 세 대의 컴퓨터가 포함될 수 있습니다. 수행 된 작업에 따라 세 컴퓨터 모두에 NetSetup.log 파일 정보가 저장됩니다. 이러한 파일의 내용을 검토하는 것은 온라인 및 오프라인 프로비저닝 오류를 해결하는 가장 일반적인 방법입니다. 관리자가 수행하는 프로비전 작업은 %WINDIR%\Debug의 NetSetup.log 파일에 기록됩니다. 관리자가 아닌 사용자가 수행하는 프로비저닝 작업은 %USERPROFILE%\Debug 폴더의 NetSetup.log 파일에 기록됩니다.

오프라인 도메인 조인 작업에 대한 자세한 내용은 오프라인 도메인 조인 단계별 가이드를 참조하세요.

NetJoinDomain 및 NetUnjoinDomain을 사용하여 도메인에 컴퓨터를 조인(및 연결 해제)하는 작업은 대상 컴퓨터의 Administrators 로컬 그룹 구성원만 수행합니다. 도메인 관리자는 위임 및 권한 할당을 사용하여 도메인에 가입하기 위한 추가 요구 사항을 설정할 수 있습니다.

요구 사항


지원되는 최소 클라이언트	Windows 8 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	lmjoin.h(Lm.h 포함)
라이브러리	Netapi32.lib
DLL	Netapi32.dll