LsaLogonUser function (ntsecapi.h)
The LsaLogonUser function authenticates a security principal's logon data by using stored credentials information.
If the authentication is successful, this function creates a new logon session and returns a user token.
When a new ticket granting ticket (TGT) is obtained by using new certificate credentials, then all of the system's TGTs and service tickets are purged. Any user service tickets that are of a compound identity are also purged.
NTSTATUS LsaLogonUser( HANDLE LsaHandle, PLSA_STRING OriginName, SECURITY_LOGON_TYPE LogonType, ULONG AuthenticationPackage, PVOID AuthenticationInformation, ULONG AuthenticationInformationLength, PTOKEN_GROUPS LocalGroups, PTOKEN_SOURCE SourceContext, PVOID *ProfileBuffer, PULONG ProfileBufferLength, PLUID LogonId, PHANDLE Token, PQUOTA_LIMITS Quotas, PNTSTATUS SubStatus );
A handle obtained from a previous call to LsaRegisterLogonProcess.
The caller is required to have SeTcbPrivilege only if one or more of the following is true:
- A Subauthentication package is used.
- KERB_S4U_LOGON is used, and the caller requests an impersonation token.
- The LocalGroups parameter is not NULL.
A string that identifies the origin of the logon attempt. For more information, see Remarks.
A value of the SECURITY_LOGON_TYPE enumeration that specifies the type of logon requested. If LogonType is Interactive or Batch, a primary token is generated to represent the new user. If LogonType is Network, an impersonation token is generated.
An identifier of the authentication package to use for the authentication. You can obtain this value by calling LsaLookupAuthenticationPackage.
A pointer to an input buffer that contains authentication information, such as user name and password. The format and content of this buffer are determined by the authentication package.
This parameter can be one of the following input buffer structures for the MSV1_0 and Kerberos authentication packages.
Authenticating an interactive user logon.
The LogonDomainName, UserName, and Password members of the MSV1_0_INTERACTIVE_LOGON structure must point to buffers in memory that are contiguous to the structure itself. The value of the AuthenticationInformationLength parameter must take into account the length of these buffers.
||Authenticating an interactive user logon.|
||Authenticating a user on initial network logon or disconnect.|
||Authenticating a user on ticket refresh, a variation of the normal workstation unlock logon.|
||Authenticating a user using an interactive smart card logon.|
||Authenticating a user using a service for user (S4U) logon.|
||Authenticating a user to unlock a workstation that has been locked during an interactive smart card logon session.|
||Authenticating a user smart card logon using LOGON32_PROVIDER_WINNT50 or LOGON32_PROVIDER_DEFAULT.|
||Authenticating a user to unlock a workstation that has been locked during a smart card logon session.|
Authenticating a user using S4U client requests. For constrained delegation, a call to LsaLogonUser is not necessary if the client logged on using an LSA-mode authentication package. On Windows operating systems, these include Kerberos, NTLM, Secure Channel, and Digest. For this call to succeed, the following must be true:
Processing the second half of an NTLM 2.0 protocol logon. The first half of this type of logon is performed by calling
LsaCallAuthenticationPackage with the MsV1_0Lm20ChallengeRequest message. For more information, see the description of MsV1_0Lm20ChallengeRequest in
This type of logon can use a subauthentication package.
||Authenticating a user with subauthentication.|
For more information about the buffer used by other authentication packages, see the documentation for those authentication packages.
The length, in bytes, of the AuthenticationInformation buffer.
A list of additional group identifiers to add to the token of the authenticated user. These group identifiers will be added, along with the default group WORLD and the logon type group (Interactive, Batch, or Network), which are automatically included in every user token.
A TOKEN_SOURCE structure that identifies the source module—for example, the session manager—and the context that may be useful to that module. This information is included in the user token and can be retrieved by calling GetTokenInformation.
A pointer to a void pointer that receives the address of an output buffer that contains authentication information, such as the logon shell and home directory.
This parameter can be one of the following output buffer structures for the MSV1_0 and Kerberos authentication packages.
For more information about the buffer used by other authentication packages, see the documentation for that authentication package.
When this buffer is no longer needed, the calling application must free this buffer by calling the LsaFreeReturnBuffer function.
A pointer to a ULONG that receives the length, in bytes, of the returned profile buffer.
A pointer to a buffer that receives an LUID that uniquely identifies the logon session. This LUID is assigned by the domain controller that authenticated the logon information.
A pointer to a handle that receives the new user token created for this session. When you have finished using the token, release it by calling the CloseHandle function.
When a primary token is returned, this parameter receives a QUOTA_LIMITS structure that contains the process quota limits assigned to the newly logged on user's initial process.
If the logon failed due to account restrictions, this parameter receives information about why the logon failed. This value is set only if the account information of the user is valid and the logon is rejected.
This parameter can be one of the following SubStatus values for the MSV1_0 authentication package.
If the function succeeds, the function returns STATUS_SUCCESS.
If the function fails, it returns an NTSTATUS code, which can be one of the following values.
||The caller's memory quota is insufficient to allocate the output buffer returned by the authentication package.|
||The user account and password are legitimate, but the user account has a restriction that prevents logon at this time. For more information, see the value stored in the SubStatus parameter.|
||The authentication information provided is not recognized by the authentication package.|
||The logon attempt failed. The reason for the failure is not specified, but typical reasons include misspelled user names and misspelled passwords.|
||No domain controllers are available to service the authentication request.|
||The specified authentication package is not recognized by the LSA.|
||The Kerberos client received a KDC certificate that is not valid. For device logon, strict KDC validation is required, so the KDC must have certificates that use the "Kerberos Authentication" template or equivalent. Also, the KDC certificate could be expired, revoked, or the client is under active attack of sending requests to the wrong server.|
||The Kerberos client is using a system certificate that is not valid. For device logon, there must be a DNS name. Also, the system certificate could be expired or the wrong one could be selected.|
For more information, see LSA Policy Function Return Values.
The LsaNtStatusToWinError function converts an NTSTATUS code to a Windows error code.
The OriginName parameter should specify meaningful information. For example, it might contain "TTY1" to indicate terminal one or "NTLM - remote node JAZZ" to indicate a network logon that uses NTLM through a remote node called "JAZZ".
You must call LsaLogonUser separately to update PKINIT device credentials for LOCAL_SYSTEM and NETWORK_SERVICE. When there is no PKINIT device credential, a successful call does no operation. When there is a PKINIT device credential, a successful call cleans up the PKINIT device credential so that only the password credential remains.
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|