LSA_AP_LOGON_USER 콜백 함수(ntsecpkg.h)
사용자의 로그온 자격 증명을 인증합니다.
이 함수는 사용자의 초기 로그온에 대해서만 호출됩니다. 후속 인증 요청은 LsaCallAuthenticationPackage를 사용해야 합니다.
LsaApLogonUser가 성공하면 로그온 세션이 만들어집니다. 또한 새로 로그온한 사용자를 나타내는 토큰을 빌드하는 데 사용되는 정보를 반환합니다.
구문
LSA_AP_LOGON_USER LsaApLogonUser;
NTSTATUS LsaApLogonUser(
[in] PLSA_CLIENT_REQUEST ClientRequest,
[in] SECURITY_LOGON_TYPE LogonType,
[in] PVOID AuthenticationInformation,
[in] PVOID ClientAuthenticationBase,
[in] ULONG AuthenticationInformationLength,
[out] PVOID *ProfileBuffer,
[out] PULONG ProfileBufferLength,
[out] PLUID LogonId,
[out] PNTSTATUS SubStatus,
[out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
[out] PVOID *TokenInformation,
[out] PLSA_UNICODE_STRING *AccountName,
[out] PLSA_UNICODE_STRING *AuthenticatingAuthority
)
{...}
매개 변수
[in] ClientRequest
LSA 클라이언트의 요청을 나타내는 불투명 LSA_CLIENT_REQUEST 버퍼에 대한 포인터입니다. 인증 패키지는 메모리를 할당하거나 해제해야 하는 클라이언트 프로세스를 식별하기 위해 이 값을 AllocateClientBuffer 및 FreeClientBuffer 에 전달할 수 있습니다.
[in] LogonType
요청된 로그온 유형을 식별하는 SECURITY_LOGON_TYPE 값입니다.
[in] AuthenticationInformation
인증 패키지와 관련된 인증 정보를 제공합니다. LSA는 이 버퍼를 해제합니다. LsaLogonUser에 전달된 것과 동일한 입력 버퍼입니다.
[in] ClientAuthenticationBase
클라이언트 프로세스 내에서 인증 정보의 주소를 제공합니다. AuthenticationInformation 버퍼 내의 포인터를 다시 매핑하는 데 필요할 수 있습니다.
[in] AuthenticationInformationLength
AuthenticationInformation 버퍼의 길이(바이트)를 나타냅니다.
[out] ProfileBuffer
클라이언트 프로세스에서 프로필 버퍼의 주소를 받는 포인터입니다. 인증 패키지는 AllocateClientBuffer 함수를 호출하여 클라이언트 프로세스 내에서 ProfileBuffer 버퍼를 할당합니다. 그러나 LSA가 로그온에 성공하지 못하는 오류가 발생하는 경우 LSA는 이 버퍼를 해제합니다.
이 버퍼의 내용은 인증 패키지에 의해 결정됩니다. LSA는 이 버퍼를 변경하지 않습니다. LsaLogonUser 함수에 값을 반환하기만 하면 됩니다.
[out] ProfileBufferLength
ProfileBuffer 버퍼의 길이를 바이트 단위로 받는 ULONG에 대한 포인터입니다.
[out] LogonId
이 로그온 세션을 고유하게 식별하는 새 로그온 ID를 수신하는 LUID 에 대한 포인터입니다. 인증 패키지는 이 LUID를 할당하고 이 로그온에 대한 로그온 세션을 만듭니다.
[out] SubStatus
계정 제한으로 인해 실패 이유를 수신하는 NTSTATUS에 대한 포인터입니다. SubStatus에서 반환되는 값은 인증 패키지에 의해 결정됩니다.
다음 표에서는 MSV1_0 및 Kerberos 인증 패키지에 대한 SubStatus 값을 나열합니다.
NTSTATUS 코드에 대한 자세한 내용은 Platform SDK와 함께 제공되는 Subauth.h 헤더 파일에서 찾을 수 있습니다.
LsaNtStatusToWinError 함수는 NTSTATUS 코드를 Windows 오류 코드로 변환합니다.
[out] TokenInformationType
만들 토큰에 포함하기 위해 반환되는 정보 유형을 나타내는 LSA_TOKEN_INFORMATION_TYPE 값의 주소를 받는 포인터입니다. 정보는 TokenInformation 버퍼에 반환됩니다.
[out] TokenInformation
토큰에 포함할 정보를 수신하는 포인터입니다. TokenInformation 버퍼의 형식과 콘텐츠는 TokenInformationType 매개 변수로 표시됩니다. 인증 패키지는 TokenInformation에서 사용하는 메모리를 할당해야 합니다. 그러나 이 메모리는 LSA에서 해제됩니다.
[out] AccountName
사용자 계정의 이름을 받는 LSA_UNICODE_STRING 구조체에 대한 포인터입니다. AccountName 은 호출의 성공 또는 실패에 관계없이 항상 반환되어야 합니다. 인증 시도를 위해 해당 문자열이 감사 레코드에 포함됩니다. 인증 패키지는 AccountName에서 사용하는 메모리를 할당해야 합니다. 그러나 이 메모리는 LSA에서 해제됩니다.
[out] AuthenticatingAuthority
선택 사항입니다. 로그온에 대한 인증 기관에 대한 설명을 수신하는 LSA_UNICODE_STRING 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다. 이 문자열은 인증 시도에 대한 감사 레코드에 포함됩니다. 인증 패키지는 AuthenticatingAuthority에서 사용하는 메모리를 할당해야 합니다. 그러나 이 메모리는 LSA에서 해제됩니다.
MSV1_0 인증 패키지는 계정의 유효성을 검사하는 도메인의 도메인 이름을 반환합니다. Kerberos 인증 패키지는 NetBIOS 도메인 이름을 반환합니다.
반환 값
함수가 성공하면 STATUS_SUCCESS 반환해야 합니다.
함수가 실패하면 다음 값 중 하나 또는 LSA 정책 함수 반환 값 중 하나일 수 있는 NTSTATUS 오류 코드를 반환해야 합니다.
| 반환 코드 | 설명 |
|---|---|
|
클라이언트의 메모리 할당량이 반환 버퍼를 할당하기에 충분하지 않으므로 로그온을 완료할 수 없습니다. |
|
인증 요청을 서비스하는 데 사용할 수 있는 도메인 컨트롤러는 없습니다. |
|
로그온 시도가 실패했습니다. 실패 이유를 지정하지 않았습니다. 일반적인 이유로는 철자가 틀린 사용자 이름 및 암호가 있습니다. |
|
사용자 계정과 암호는 합법적이었지만 사용자 계정 제한으로 인해 현재 로그온할 수 없습니다. 자세한 내용은 SubStatus 매개 변수를 참조하세요. |
|
제공된 인증 정보는 지정된 인증 패키지에서 인식되지 않습니다. |
호출 애플리케이션은 LsaNtStatusToWinError 함수를 사용하여 NTSTATUS 코드를 Windows 오류 코드로 변환할 수 있습니다.
설명
인증 패키지는 LsaApLogonUser, LsaApLogonUserEx 또는 LsaApLogonUserEx2 함수 중 하나를 구현해야 합니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | ntsecpkg.h |