LSA_AP_LOGON_USER_EX2 callback function (ntsecpkg.h)

Article
10/13/2021

Used to authenticate a user logon attempt on the user's initial logon. A new logon session is established for the user, and validation information for the user is returned.

Syntax

LSA_AP_LOGON_USER_EX2 LsaApLogonUserEx2;

NTSTATUS LsaApLogonUserEx2(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID ProtocolSubmitBuffer,
  [in]  PVOID ClientBufferBase,
  [in]  ULONG SubmitBufferSize,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferSize,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PUNICODE_STRING *AccountName,
  [out] PUNICODE_STRING *AuthenticatingAuthority,
  [out] PUNICODE_STRING *MachineName,
  [out] PSECPKG_PRIMARY_CRED PrimaryCredentials,
  [out] PSECPKG_SUPPLEMENTAL_CRED_ARRAY *SupplementalCredentials
)
{...}

Parameters

[in] ClientRequest

Pointer to a LSA_CLIENT_REQUEST opaque buffer representing the client's request.

[in] LogonType

SECURITY_LOGON_TYPE value that identifies the type of logon.

[in] ProtocolSubmitBuffer

Buffer that supplies the authentication information specific to the authentication package.

[in] ClientBufferBase

Buffer that provides the address within the client process at which the authentication information was resident. This might be necessary to fix any pointers within the authentication information buffer.

[in] SubmitBufferSize

A ULONG value that indicates the size, in bytes, of the authentication information buffer.

[out] ProfileBuffer

Pointer that receives the address of the profile buffer in the client process. The authentication package is responsible for allocating ProfileBuffer within the client process by calling the AllocateClientBuffer function. However, if the LSA subsequently encounters an error which prevents a successful logon, then the LSA will take care of freeing this buffer.

The contents of this buffer are determined by the authentication package. The LSA does not alter this buffer; it simply returns the value to the LsaLogonUser function.

[out] ProfileBufferSize

Pointer to a ULONG that receives the size of the ProfileBuffer buffer.

[out] LogonId

Pointer to an LUID variable that receives the new logon ID that uniquely identifies this logon session. The authentication package is responsible for allocating this LUID and creating the LSA logon session for this logon.

[out] SubStatus

Pointer to an NTSTATUS that receives the reason for failures due to account restrictions. The values returned in SubStatus are determined by the authentication package.

The following table lists the SubStatus values for the MSV1_0 and Kerberos authentication packages.

Value	Meaning
STATUS_INVALID_LOGON_HOURS	The user account has time restrictions; it cannot be used to log on at this time.
STATUS_INVALID_WORKSTATION	The user account has workstation restrictions; it cannot be used to log on to the current workstation.
STATUS_PASSWORD_EXPIRED	The user account password has expired.
STATUS_ACCOUNT_DISABLED	The user account is currently disabled and cannot be used to log on.

More information about NTSTATUS codes can be found in the Subauth.h header file shipped with the Platform SDK.

The LsaNtStatusToWinError function converts an NTSTATUS code to a Windows error code.

[out] TokenInformationType

Pointer that receives the address of an LSA_TOKEN_INFORMATION_TYPE value that indicates the type of information returned for inclusion in the token to be created. The information is returned by means of the TokenInformation parameter.

[out] TokenInformation

Pointer that receives the address of information to be included in the token. The format and content of TokenInformation are indicated by the TokenInformationType parameter. Your authentication package is responsible for allocating the memory used by TokenInformation; however, this memory will be freed by the LSA.

[out] AccountName

Pointer to an LSA_UNICODE_STRING structure that receives the name of the user account. AccountName must always be returned regardless of the success or failure of the call; its string is included in the audit record for an authentication attempt. Your authentication package is responsible for allocating the memory used by AccountName; however, this memory will be freed by the LSA.

[out] AuthenticatingAuthority

Optional. Pointer to an LSA_UNICODE_STRING structure that receives the description of the authenticating authority for the logon. This parameter may be NULL. This string is included in the audit record for an authentication attempt. Your authentication package is responsible for allocating the memory used by AuthenticatingAuthority; however, this memory will be freed by the LSA.

The MSV1_0 authentication package returns the domain name of the domain validating the account. The Kerberos authentication package returns the NetBIOS domain name.

[out] MachineName

Optional. Pointer that receives the address of a UNICODE_STRING structure containing the name of the client's computer. This string may optionally be omitted. This string is included in the audit record for this authentication attempt. Your authentication package is responsible for allocating the memory used by MachineName; however, this memory will be freed by the LSA.

The MSV1_0 authentication package returns the NetBIOS name of the client's workstation.

[out] PrimaryCredentials

Pointer to a SECPKG_PRIMARY_CRED structure that returns primary credentials for handing to other packages.

[out] SupplementalCredentials

Pointer to a SECPKG_SUPPLEMENTAL_CRED_ARRAY array of supplemental credentials for other packages.

Return value

If the function succeeds, it should return STATUS_SUCCESS.

Otherwise, it should return an NTSTATUS error code, which can be one of the following values or one of the LSA Policy Function Return Values.

Return code	Description
STATUS_QUOTA_EXCEEDED	The logon could not be completed because the client's memory quota is insufficient to allocate the return buffer.
STATUS_NO_LOGON_SERVERS	No domain controllers are available to service the authentication request.
STATUS_LOGON_FAILURE	The logon attempt failed. The reason for failure is not specified; typical reasons include misspelled user names and passwords.
STATUS_ACCOUNT_RESTRICTION	The user account and password were legitimate, but user account restrictions preventing successful logon at this time. For additional information see the SubStatus parameter.
STATUS_BAD_VALIDATION_CLASS	The authentication information provided is not recognized by the authentication package.
STATUS_INVALID_LOGON_TYPE	LogonType was not valid.
STATUS_LOGON_SESSION_COLLISION	The logon ID selected for this logon session (in the LogonId parameter) already exists.
STATUS_NETLOGON_NOT_STARTED	The SAM database or Netlogon service is required, but is not available.
STATUS_NO_MEMORY	The client's virtual memory or pagefile quotas are insufficient to allocate the return buffer.

Calling applications can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

Authentication packages must implement one of the following functions: LsaApLogonUser, LsaApLogonUserEx, or LsaApLogonUserEx2.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ntsecpkg.h