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.

Syntax

NTSTATUS LsaLogonUser(
  [in]           HANDLE              LsaHandle,
  [in]           PLSA_STRING         OriginName,
  [in]           SECURITY_LOGON_TYPE LogonType,
  [in]           ULONG               AuthenticationPackage,
  [in]           PVOID               AuthenticationInformation,
  [in]           ULONG               AuthenticationInformationLength,
  [in, optional] PTOKEN_GROUPS       LocalGroups,
  [in]           PTOKEN_SOURCE       SourceContext,
  [out]          PVOID               *ProfileBuffer,
  [out]          PULONG              ProfileBufferLength,
  [out]          PLUID               LogonId,
  [out]          PHANDLE             Token,
  [out]          PQUOTA_LIMITS       Quotas,
  [out]          PNTSTATUS           SubStatus
);

Parameters

[in] LsaHandle

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.
If SeTcbPrivilege is not required, call LsaConnectUntrusted to obtain the handle.

[in] OriginName

A string that identifies the origin of the logon attempt. For more information, see Remarks.

[in] LogonType

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.

[in] AuthenticationPackage

An identifier of the authentication package to use for the authentication. You can obtain this value by calling LsaLookupAuthenticationPackage.

[in] AuthenticationInformation

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.

Value Meaning
MSV1_0_INTERACTIVE_LOGON
MSV1_0
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.

KERB_INTERACTIVE_LOGON
Kerberos
Authenticating an interactive user logon.
KERB_TICKET_LOGON
Kerberos
Authenticating a user on initial network logon or disconnect.
KERB_TICKET_UNLOCK_LOGON
Kerberos
Authenticating a user on ticket refresh, a variation of the normal workstation unlock logon.
KERB_CERTIFICATE_LOGON
Kerberos
Authenticating a user using an interactive smart card logon.
KERB_CERTIFICATE_S4U_LOGON
Kerberos
Authenticating a user using a service for user (S4U) logon.
KERB_CERTIFICATE_UNLOCK_LOGON
Kerberos
Authenticating a user to unlock a workstation that has been locked during an interactive smart card logon session.
KERB_SMARTCARD_LOGON
Kerberos
Authenticating a user smart card logon using LOGON32_PROVIDER_WINNT50 or LOGON32_PROVIDER_DEFAULT.
KERB_SMARTCARD_UNLOCK_LOGON
Kerberos
Authenticating a user to unlock a workstation that has been locked during a smart card logon session.
KERB_S4U_LOGON
Kerberos
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:
  • The caller must be a domain account (this includes LOCAL_SYSTEM if the computer is a domain member).
  • If using a service account, the account must have SeTcbPrivilege set on the local computer to get an impersonation token. Otherwise, the identity token is used.
  • The caller must be a member of the Pre-Windows 2000 Compatible Access or have read access to the group memberships of the client. Membership in the Windows Authorization Access group guarantees read access to group membership of the client. For information about how to configure the Windows Authorization Access group, see the Microsoft Knowledge Base.
The ClientUpn and ClientRealm members of the KERB_S4U_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.
MSV1_0_LM20_LOGON
MSV1_0
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 MSV1_0_PROTOCOL_MESSAGE_TYPE.

This type of logon can use a subauthentication package.

MSV1_0_SUBAUTH_LOGON
MSV1_0
Authenticating a user with subauthentication.
 

For more information about the buffer used by other authentication packages, see the documentation for those authentication packages.

[in] AuthenticationInformationLength

The length, in bytes, of the AuthenticationInformation buffer.

[in, optional] LocalGroups

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.

[in] SourceContext

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.

[out] ProfileBuffer

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.

Value Meaning
MSV1_0_INTERACTIVE_PROFILE
MSV1_0
An interactive user's logon profile.
KERB_TICKET_PROFILE
Kerberos
Logon, disconnect, and ticket refresh authentication output.
MSV1_0_LM20_LOGON
MSV1_0
Output when processing the second half of a NTLM 2.0 protocol logon.
MSV1_0_LM20_LOGON_PROFILE
MSV1_0
Output when using authentication with subauthentication.
 

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.

[out] ProfileBufferLength

A pointer to a ULONG that receives the length, in bytes, of the returned profile buffer.

[out] LogonId

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.

[out] Token

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.

[out] Quotas

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.

[out] SubStatus

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.

Value Meaning
STATUS_INVALID_LOGON_HOURS
The user account has time restrictions and cannot be used to log on at this time.
STATUS_INVALID_WORKSTATION
The user account has workstation restrictions and cannot be used to log on from 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.

Return value

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.

Value Description
STATUS_QUOTA_EXCEEDED
The caller's memory quota is insufficient to allocate the output buffer returned by the authentication package.
STATUS_ACCOUNT_RESTRICTION
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.
STATUS_BAD_VALIDATION_CLASS
The authentication information provided is not recognized by the authentication package.
STATUS_LOGON_FAILURE
The logon attempt failed. The reason for the failure is not specified, but typical reasons include misspelled user names and misspelled passwords.
STATUS_NO_LOGON_SERVERS
No domain controllers are available to service the authentication request.
STATUS_NO_SUCH_PACKAGE
The specified authentication package is not recognized by the LSA.
STATUS_PKINIT_FAILURE
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.
STATUS_PKINIT_CLIENT_FAILURE
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.

Remarks

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.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header ntsecapi.h
Library Secur32.lib
DLL Secur32.dll

See also

Allowing Anonymous Access

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage