LSA_AP_LOGON_USER 콜백 함수(ntsecpkg.h)

아티클
08/25/2023

사용자의 로그온 자격 증명을 인증합니다.

이 함수는 사용자의 초기 로그온에 대해서만 호출됩니다. 후속 인증 요청은 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 값을 나열합니다.

값	의미
STATUS_INVALID_LOGON_HOURS	사용자 계정에는 시간 제한이 있습니다. 지금은 로그온하는 데 사용할 수 없습니다.
STATUS_INVALID_WORKSTATION	사용자 계정에는 워크스테이션 제한이 있습니다. 현재 워크스테이션에 로그온하는 데 사용할 수 없습니다.
STATUS_PASSWORD_EXPIRED	사용자 계정 암호가 만료되었습니다.
STATUS_ACCOUNT_DISABLED	사용자 계정은 현재 사용하지 않도록 설정되어 있으며 로그온하는 데 사용할 수 없습니다.

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 오류 코드를 반환해야 합니다.

반환 코드	설명
STATUS_NO_MEMORY	클라이언트의 메모리 할당량이 반환 버퍼를 할당하기에 충분하지 않으므로 로그온을 완료할 수 없습니다.
STATUS_NO_LOGON_SERVERS	인증 요청을 서비스하는 데 사용할 수 있는 도메인 컨트롤러는 없습니다.
STATUS_LOGON_FAILURE	로그온 시도가 실패했습니다. 실패 이유를 지정하지 않았습니다. 일반적인 이유로는 철자가 틀린 사용자 이름 및 암호가 있습니다.
STATUS_ACCOUNT_RESTRICTION	사용자 계정과 암호는 합법적이었지만 사용자 계정 제한으로 인해 현재 로그온할 수 없습니다. 자세한 내용은 SubStatus 매개 변수를 참조하세요.
STATUS_BAD_VALIDATION_CLASS	제공된 인증 정보는 지정된 인증 패키지에서 인식되지 않습니다.

호출 애플리케이션은 LsaNtStatusToWinError 함수를 사용하여 NTSTATUS 코드를 Windows 오류 코드로 변환할 수 있습니다.

설명

인증 패키지는 LsaApLogonUser, LsaApLogonUserEx 또는 LsaApLogonUserEx2 함수 중 하나를 구현해야 합니다.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	ntsecpkg.h