LsaApLogonUser function
Authenticates a user's logon credentials.
This function is called only for a user's initial logon. Subsequent authentication requests must use LsaCallAuthenticationPackage.
If LsaApLogonUser succeeds, it creates a logon session. It also returns information used to build the token representing the newly logged-on user.
Syntax
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 );
Parameters
- ClientRequest [in]
-
Pointer to an opaque LSA_CLIENT_REQUEST buffer that represents the LSA client's request. Your authentication package can pass this value into AllocateClientBuffer and FreeClientBuffer in order to identify the client process in which memory should be allocated or freed.
- LogonType [in]
-
A SECURITY_LOGON_TYPE value identifying the type of logon requested.
- AuthenticationInformation [in]
-
Supplies the authentication information specific to the authentication package. The LSA will free this buffer. This is the same input buffer passed into LsaLogonUser.
- ClientAuthenticationBase [in]
-
Provides the address of the authentication information within the client process. This may be necessary to remap any pointers within the AuthenticationInformation buffer.
- AuthenticationInformationLength [in]
-
Indicates the length, in bytes, of the AuthenticationInformation buffer.
- ProfileBuffer [out]
-
Pointer that receives the address of the profile buffer in the client process. The authentication package is responsible for allocating the ProfileBuffer buffer within the client process by calling the AllocateClientBuffer function. However, if the LSA subsequently encounters an error that prevents a successful logon, the LSA will free 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.
- ProfileBufferLength [out]
-
Pointer to a ULONG that receives the length of the ProfileBuffer buffer, in bytes.
- LogonId [out]
-
Pointer to an LUID that receives the new logon ID that uniquely identifies this logon session. The authentication package is responsible for allocating this LUID, and creating the logon session for this logon.
- SubStatus [out]
-
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.
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.
- TokenInformationType [out]
-
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 in the TokenInformation buffer.
- TokenInformation [out]
-
Pointer that receives information to be included in the token. The format and content of the TokenInformation buffer 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.
- AccountName [out]
-
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.
- AuthenticatingAuthority [out]
-
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.
Return value
If the function succeeds, it should return STATUS_SUCCESS.
If the function fails, 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 |
|---|---|
|
The logon could not be completed because the client's memory quota is insufficient to allocate the return buffer. |
|
No domain controllers are available to service the authentication request. |
|
The logon attempt failed. The reason for failure is not specified; typical reasons include misspelled user names and passwords. |
|
The user account and password were legitimate, but user account restrictions prevent logon at this time. For additional information, see the SubStatus parameter. |
|
The authentication information provided is not recognized by the specified authentication package. |
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
|
Minimum supported client |
Windows XP [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
Header |
|
See also
- LSA_CLIENT_REQUEST
- LSA_TOKEN_INFORMATION_TYPE
- LSA_UNICODE_STRING
- LsaApLogonUserEx
- LsaApLogonUserEx2
- LsaCallAuthenticationPackage