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 헤더 파일에 정의된 다음 값 중 하나 이상일 수 있습니다.
| 값 | 의미 |
|---|---|
|
호출자가 권한으로 계정을 생성해야 하는 경우 이 옵션을 사용하면 이전 버전의 Windows에서 실행되는 도메인 컨트롤러와의 상호 운용성을 가능하게 하는 계정 만들기 함수를 사용하여 실패 시 재시도가 발생합니다.
lpMachineAccountOU는 하위 권한 지원을 사용할 때 지원되지 않습니다. |
|
명명된 계정이 이미 있는 경우 기존 계정을 다시 사용하려고 시도합니다.
이 옵션을 사용하려면 이 작업에 충분한 자격 증명(도메인 관리자 또는 개체 소유자)이 필요합니다. |
|
소문자의 컴퓨터 이름인 기본 컴퓨터 계정 암호를 사용합니다. 이는 주로 미리 만들어진 계정이 일반적으로 이 기본 암호를 사용하는 이전의 안전하지 않은 조인 모델을 지원하기 위한 것입니다.
참고 가능하면 애플리케이션에서 이 옵션을 사용하지 않아야 합니다. 이 옵션과 dwOptions가 안전하지 않은 조인에 대해 NETSETUP_JOIN_UNSECURE 설정된 NetJoinDomain 함수는 이전 버전의 Windows에서만 사용해야 합니다.
|
|
도메인의 도메인 컨트롤러에서 계정을 찾으려고 시도하지 마세요. 이 옵션을 사용하면 작업이 더 빨라지지만 호출자가 동일한 이름의 계정이 최근에 만들어지지 않았음을 확신하는 경우에만 사용해야 합니다.
이 옵션은 lpDcName 매개 변수가 지정된 경우에만 유효합니다. 필수 구성 요소가 충족되면 이 옵션을 사용하면 일괄 처리와 같은 시나리오에 유용한 프로비저닝을 더 빠르게 수행할 수 있습니다. |
|
이 옵션은 로컬 컴퓨터의 모든 루트 인증 기관 인증서를 검색하고 프로비저닝 패키지의 일부로 인증서 템플릿 이름이 제공되지 않는 경우 프로비저닝 패키지에 추가합니다(pProvisioningParams 매개 변수에 전달된 NETSETUP_PROVISIONING_PARAMS 구조체의 aCertTemplateNames 멤버는 NetCreateProvisioningPackage 함수가 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를 지원하는 도메인 컨트롤러가 필요합니다. |
|
계정이 이미 도메인에 있고 NETSETUP_PROVISION_REUSE_ACCOUNT 비트가 dwOptions 매개 변수에 지정되지 않았습니다. |
|
워크스테이션 서비스가 시작되지 않았습니다. |
|
이 스레드에 대한 원격 프로시저 호출이 이미 진행 중입니다. |
|
원격 프로시저 호출 프로토콜 시퀀스는 지원되지 않습니다. |
설명
NetProvisionComputerAccount 함수는 오프라인 조인 작업을 위해 Windows 7 및 Windows Server 2008 R2에서 지원됩니다. Windows 8 또는 Windows Server 2008 R2에서는 NetProvisionComputerAccount 함수 대신 NetCreateProvisioningPackage 함수를 사용하는 것이 좋습니다.
NetProvisionComputerAccount 함수는 NetRequestOfflineDomainJoin 함수를 사용하여 오프라인 도메인 조인 작업에서 나중에 사용할 컴퓨터 계정을 프로비전하는 데 사용됩니다. 오프라인 도메인 조인 시나리오에서는 다음과 같이 이러한 함수를 사용합니다.
- NetProvisionComputerAccount 는 Active Directory에서 컴퓨터 개체를 만들고 구성하는 데 필요한 네트워크 작업을 수행하기 위해 먼저 호출되는 프로비저닝 함수입니다. NetProvisionComputerAccount의 출력은 다음 단계에서 사용되는 직렬화된 메타데이터의 불투명 이진 Blob입니다.
- 그런 다음, 이미지 초기화 함수인 NetRequestOfflineDomainJoin을 호출하여 NetProvisionComputerAccount 프로비저닝 함수의 출력을 설치 중에 사용할 Windows 운영 체제 이미지에 삽입합니다.
NetProvisionComputerAccount 함수는 도메인에서 컴퓨터 계정을 만들거나 다시 사용하고, 필요한 모든 메타데이터를 수집하고, 불투명 버전이 지정된 이진 Blob 또는 무인 설치 응답 파일에 포함하기 위한 텍스트로 반환합니다. 불투명 이진 Blob은 네트워크 작업 없이 첫 번째 부팅 중에 도메인 조인을 완료하는 데 필요한 모든 입력을 제공하는 오프라인 도메인 조인 요청 작업에서 사용할 수 있습니다(로컬 상태 업데이트만 해당).
보안 참고 사항: NetProvisionComputerAccount 함수에서 반환된 Blob에는 매우 중요한 데이터가 포함됩니다. 일반 텍스트 암호처럼 안전하게 처리해야 합니다. Blob에는 도메인 이름, 도메인 컨트롤러 이름 및 도메인의 SID(보안 ID)를 포함하여 도메인에 대한 컴퓨터 계정 암호 및 기타 정보가 포함됩니다. Blob이 물리적으로 또는 네트워크를 통해 전송되는 경우 안전하게 전송하려면 주의해야 합니다. 디자인에서는 이 데이터를 보호하기 위한 프로비저닝을 수행하지 않습니다. 이 문제는 도메인 사용자 암호를 포함하여 많은 비밀을 전달할 수 있는 무인 설정 응답 파일에서 현재 존재합니다. 호출자는 Blob 및 무인 설치 파일을 보호해야 합니다. 이 문제에 대한 해결 방법은 다양합니다. 예를 들어 미리 교환된 키를 사용하여 소비자와 프로비전 엔터티 간의 세션을 암호화하여 불투명 Blob의 보안 전송을 가능하게 할 수 있습니다.
NetProvisionComputerAccount 함수에 의해 pProvisionBinData 매개 변수에 반환된 불투명 Blob은 서로 다른 버전의 Windows(클라이언트, 프로비저닝 머신 및 도메인 컨트롤러 조인) 간의 상호 운용성 및 서비스 가능성 시나리오를 허용하도록 버전이 지정됩니다. 오프라인 조인 시나리오는 현재 NetProvisionComputerAccount 함수에서 반환된 Blob의 수명을 제한하지 않습니다.
오프라인 도메인 조인의 경우 수행되는 액세스 검사 도메인의 구성에 따라 달라집니다. 컴퓨터 계정 만들기는 다음 세 가지 방법을 사용하여 사용하도록 설정됩니다.
- 도메인 관리자는 컴퓨터 계정을 만들 권한이 있습니다.
- 컨테이너의 SD는 컴퓨터 계정을 만들 수 있는 권한을 위임할 수 있습니다.
- 기본적으로 인증된 사용자는 권한으로 컴퓨터 계정을 만들 수 있습니다. 인증된 사용자는 도메인에서 할당량으로 지정된 제한된 수의 계정을 만드는 것으로 제한됩니다(기본값은 10). 자세한 내용은 Active Directory 스키마의 ms-DS-MachineAccountQuota 특성을 참조하세요.
NetProvisionComputerAccount 함수는 쓰기 가능한 도메인 컨트롤러에서만 작동하며 읽기 전용 도메인 컨트롤러에 대해 작동하지 않습니다. 쓰기 가능한 도메인 컨트롤러에 대해 프로비전이 수행되고 계정이 읽기 전용 도메인 컨트롤러에 복제되면 오프라인 도메인 조인 작업의 다른 부분에는 도메인 컨트롤러에 대한 액세스가 필요하지 않습니다.
NetProvisionComputerAccount 함수가 성공하면 pProvisionBinData 또는 pProvisionTextData 매개 변수(NULL이 아닌 매개 변수에 따라)의 포인터가 오프라인 조인 작업 또는 무인 설치 파일의 텍스트로 사용할 serialize된 데이터와 함께 반환됩니다.
오프라인 도메인 조인 작업에 대한 자세한 내용은 오프라인 도메인 조인 단계별 가이드를 참조하세요.
NetJoinDomain 및 NetUnjoinDomain을 사용하여 도메인에 컴퓨터를 조인(및 연결 해제)하는 작업은 대상 컴퓨터의 Administrators 로컬 그룹 구성원만 수행할 수 있습니다. 도메인 관리자는 위임 및 권한 할당을 사용하여 도메인에 가입하기 위한 추가 요구 사항을 설정할 수 있습니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows 7 [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 R2 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | lmjoin.h(Lm.h 포함) |
| 라이브러리 | Netapi32.lib |
| DLL | Netapi32.dll |