LogonUserA 함수(winbase.h)

아티클
03/03/2024

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

구문

BOOL LogonUserA(
  [in]           LPCSTR  lpszUsername,
  [in, optional] LPCSTR  lpszDomain,
  [in, optional] LPCSTR  lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

매개 변수

[in] lpszUsername

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

[in, optional] lpszDomain

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

[in, optional] lpszPassword

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

[in] dwLogonType

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

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

[in] dwLogonProvider

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

값	의미
LOGON32_PROVIDER_DEFAULT	시스템에 표준 로그온 공급자를 사용합니다. 도메인 이름에 대해 NULL을 전달하고 사용자 이름이 UPN 형식이 아닌 경우 기본 보안 공급자는 협상입니다. 이 경우 기본 공급자는 NTLM입니다.
LOGON32_PROVIDER_WINNT50	협상 로그온 공급자를 사용합니다.
LOGON32_PROVIDER_WINNT40	NTLM 로그온 공급자를 사용합니다.

[out] phToken

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

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

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

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

반환 값

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

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

설명

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

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

Passport 계정에 로그온하지 않는 한 이 함수에는 SE_TCB_NAME 권한이 필요하지 않습니다.

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

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

LogonUser 호출에 성공하면 시스템은 공급자의 NPLogonNotify 진입점 함수를 호출하여 로그온이 발생했음을 네트워크 공급자에게 알릴 수 있습니다.

예제

다음 코드를 사용하여 LocalService 토큰을 생성할 수 있습니다.

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

참고

winbase.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 LogonUser를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Advapi32.lib
DLL	Advapi32.dll