LogonUserExExW 함수

아티클
06/13/2023

LogonUserExW 함수는 사용자를 로컬 컴퓨터에 로그온하려고 시도합니다. 로컬 컴퓨터는 LogonUserExW 가 호출된 컴퓨터입니다. LogonUserExW를 사용하여 원격 컴퓨터에 로그온할 수 없습니다. 사용자 이름 및 도메인을 사용하여 사용자를 지정하고 일반 텍스트 암호를 사용하여 사용자를 인증 합니다. 함수가 성공하면 로그온한 사용자를 나타내는 토큰에 대한 핸들을 받습니다. 그런 다음 이 토큰 핸들을 사용하여 지정된 사용자를 가장하거나 대부분의 경우 지정된 사용자의 컨텍스트에서 실행되는 프로세스를 만들 수 있습니다.

이 함수는 로그온이 성공할 때 호출자에게 반환되는 토큰에 추가되는 하나 이상의 SID(보안 식별자) 집합인 pTokenGroups라는 추가 매개 변수를 사용한다는 점을 제외하고 LogonUserEx 함수와 유사합니다.

이 함수는 공용 헤더에 선언되지 않으며 연결된 가져오기 라이브러리가 없습니다. Advapi32.dll 동적으로 연결하려면 LoadLibrary 및 GetProcAddress 함수를 사용해야 합니다.

구문

BOOL WINAPI LogonUserExExW(
  _In_      LPTSTR        lpszUsername,
  _In_opt_  LPTSTR        lpszDomain,
  _In_opt_  LPTSTR        lpszPassword,
  _In_      DWORD         dwLogonType,
  _In_      DWORD         dwLogonProvider,
  _In_opt_  PTOKEN_GROUPS pTokenGroups,
  _Out_opt_ PHANDLE       phToken,
  _Out_opt_ PSID          *ppLogonSid,
  _Out_opt_ PVOID         *ppProfileBuffer,
  _Out_opt_ LPDWORD       pdwProfileLength,
  _Out_opt_ PQUOTA_LIMITS pQuotaLimits
);

매개 변수

lpszUsername [in]

사용자의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 로그온할 사용자 계정의 이름입니다. UPN( 사용자 계정 이름 ) 형식을 사용하는 경우 lpszDomain 매개 변수는 NULL이어야 합니다.

lpszDomain [in, optional]

계정 데이터베이스에 lpszUsername 계정이 포함된 도메인 또는 서버의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수가 NULL이면 사용자 이름을 UPN 형식으로 지정해야 합니다. 이 매개 변수가 "."인 경우 함수는 로컬 계정 데이터베이스만 사용하여 계정의 유효성을 검사합니다.

lpszPassword [in, optional]

lpszUsername으로 지정된 사용자 계정의 일반 텍스트 암호를 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 암호 사용을 마쳤으면 SecureZeroMemory 함수를 호출하여 메모리에서 암호를 지웁 암호 보호에 대한 자세한 내용은 암호 처리를 참조하세요.

dwLogonType [in]

수행할 로그온 작업의 유형입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
LOGON32_LOGON_INTERACTIVE 2	이 로그온 유형은 터미널 서버, 원격 셸 또는 유사한 프로세스에서 로그온하는 사용자와 같이 컴퓨터를 대화형으로 사용하는 사용자를 위한 것입니다. 이 로그온 유형은 연결이 끊긴 작업에 대한 로그온 정보를 캐싱하는 데 추가 비용이 듭니다. 따라서 메일 서버와 같은 일부 클라이언트/서버 애플리케이션에는 적합하지 않습니다.
LOGON32_LOGON_NETWORK 3	이 로그온 유형은 고성능 서버가 일반 텍스트 암호를 인증하기 위한 것입니다. LogonUserExW 함수는 이 로그온 형식에 대한 자격 증명을 캐시하지 않습니다.
LOGON32_LOGON_BATCH 4	이 로그온 유형은 직접 개입 없이 사용자를 대신하여 프로세스가 실행될 수 있는 일괄 처리 서버를 위한 것입니다. 이 유형은 메일 또는 웹 서버와 같이 한 번에 많은 일반 텍스트 인증 시도를 처리하는 고성능 서버용이기도 합니다. LogonUserExW 함수는 이 로그온 형식에 대한 자격 증명을 캐시하지 않습니다.
LOGON32_LOGON_SERVICE 5	서비스 유형 로그온을 나타냅니다. 제공된 계정에는 서비스 권한이 활성화되어 있어야 합니다.
LOGON32_LOGON_UNLOCK 7	이 로그온 유형은 컴퓨터를 대화형으로 사용할 사용자를 로그온하는 GINA DLL용입니다. 이 로그온 유형은 워크스테이션이 잠금 해제된 시기를 보여 주는 고유한 감사 레코드를 생성할 수 있습니다.
LOGON32_LOGON_NETWORK_CLEARTEXT 8	이 로그온 형식은 인증 패키지의 이름과 암호를 유지하므로 서버가 클라이언트를 가장하는 동안 다른 네트워크 서버에 연결할 수 있습니다. 서버는 클라이언트에서 일반 텍스트 자격 증명을 수락하고, LogonUserExW를 호출하고, 사용자가 네트워크를 통해 시스템에 액세스할 수 있는지 확인하고, 다른 서버와 계속 통신할 수 있습니다.
LOGON32_LOGON_NEW_CREDENTIALS 9	이 로그온 유형을 사용하면 호출자가 현재 토큰을 복제하고 아웃바운드 연결에 대한 새 자격 증명을 지정할 수 있습니다. 새 로그온 세션에는 동일한 로컬 식별자가 있지만 다른 네트워크 연결에 다른 자격 증명을 사용합니다. 이 로그온 유형은 LOGON32_PROVIDER_WINNT50 로그온 공급자에서만 지원됩니다.

dwLogonProvider [in]

로그온 공급자입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
LOGON32_PROVIDER_DEFAULT	시스템에 표준 로그온 공급자를 사용합니다. 기본 보안 공급자 는 NTLM입니다.
LOGON32_PROVIDER_WINNT50	협상 로그온 공급자를 사용합니다.
LOGON32_PROVIDER_WINNT40	NTLM 로그온 공급자를 사용합니다.

pTokenGroups [in, optional]

이 함수가 성공적으로 로그온할 때 수신하는 토큰에 추가되는 그룹 SID 목록을 지정하는 TOKEN_GROUPS 구조체에 대한 포인터입니다. 토큰에 추가된 모든 SID는 그룹 확장에도 영향을 줍니다. 예를 들어 추가된 SID가 로컬 그룹의 구성원인 경우 해당 그룹도 수신된 액세스 토큰에 추가됩니다.

이 매개 변수가 NULL이 아닌 경우 이 함수의 호출자는 SE_TCB_PRIVILEGE 권한을 부여하고 사용하도록 설정해야 합니다.

phToken [out, optional]

지정된 사용자를 나타내는 토큰에 대한 핸들을 수신하는 핸들 변수에 대한 포인터입니다.

ImpersonateLoggedOnUser 함수에 대한 호출에서 반환된 핸들을 사용할 수 있습니다.

대부분의 경우 반환된 핸들은 CreateProcessAsUser 함수 호출에 사용할 수 있는 기본 토큰입니다. 그러나 LOGON32_LOGON_NETWORK 플래그를 지정하는 경우 LogonUserExW는 DuplicateTokenEx를 호출하여 가장 토큰을 기본 토큰으로 변환하지 않는 한 CreateProcessAsUser에서 사용할 수 없는 가장 토큰을 반환합니다.

이 핸들이 더 이상 필요하지 않으면 CloseHandle 함수를 호출하여 닫습니다.

ppLogonSid [out, optional]

로그온한 사용자의 SID를 수신하는 SID에 대한 포인터에 대한 포인터입니다.

SID 사용을 마쳤으면 LocalFree 함수를 호출하여 해제합니다.

ppProfileBuffer [out, optional]

로그온한 사용자 프로필이 포함된 버퍼의 주소를 수신하는 포인터에 대한 포인터입니다.

pdwProfileLength [out, optional]

프로필 버퍼의 길이를 수신하는 DWORD 에 대한 포인터입니다.

pQuotaLimits [out, optional]

로그온한 사용자의 할당량에 대한 정보를 수신하는 QUOTA_LIMITS 구조체에 대한 포인터입니다.

반환 값

함수가 성공하면 함수는 0이 아닌 값을 반환합니다.

함수가 실패하면 0을 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

LOGON32_LOGON_NETWORK 로그온 형식이 가장 빠르지만 다음과 같은 제한 사항이 있습니다.

함수는 기본 토큰이 아닌 가장 토큰을 반환합니다. CreateProcessAsUser 함수에서는 이 토큰을 직접 사용할 수 없습니다. 그러나 DuplicateTokenEx 함수를 호출하여 토큰을 기본 토큰으로 변환한 다음 CreateProcessAsUser에서 사용할 수 있습니다.
토큰을 기본 토큰으로 변환하고 CreateProcessAsUser 에서 사용하여 프로세스를 시작하는 경우 새 프로세스는 리디렉터를 통해 원격 서버 또는 프린터와 같은 다른 네트워크 리소스에 액세스할 수 없습니다. 예외는 네트워크 리소스가 액세스 제어되지 않는 경우 새 프로세스에서 액세스할 수 있다는 것입니다.

lpszUsername으로 지정된 계정에는 필요한 계정 권한이 있어야 합니다. 예를 들어 LOGON32_LOGON_INTERACTIVE 플래그가 있는 사용자에 로그온하려면 사용자(또는 사용자가 속한 그룹)에 SE_INTERACTIVE_LOGON_NAME 계정이 있어야 합니다. 다양한 로그온 작업에 영향을 주는 계정 권한 목록은 계정 개체 액세스 권한을 참조하세요.

하나 이상의 토큰이 있는 경우 사용자는 로그온된 것으로 간주됩니다. CreateProcessAsUser를 호출한 다음 토큰을 닫으면 프로세스(및 모든 자식 프로세스)가 종료될 때까지 사용자가 계속 로그온됩니다.

선택적 pTokenGroups 매개 변수가 제공된 경우 LSA는 로컬 SID 또는 로그온 SID를 자동으로 추가하지 않습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
버전	LogonUserExW는 일반 배포 릴리스와 함께Windows Server 2003 또는 Windows XP에서도 사용할 수 있습니다.
헤더	Winbasep.h
DLL	Advapi32.dll

추가 정보

클라이언트/서버 Access Control
클라이언트/서버 Access Control 함수
CloseHandle
CreateProcessAsUser
DuplicateTokenEx
ImpersonateLoggedOnUser
LogonUserEx
QUOTA_LIMITS

다음을 통해 공유

LogonUserExExW 함수

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

추가 리소스