Expand Minimize

LsaLogonUser function

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_opt_  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

LsaHandle [in]

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.

OriginName [in]

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

LogonType [in]

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.

AuthenticationPackage [in]

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

AuthenticationInformation [in]

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.

ValueMeaning
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.

AuthenticationInformationLength [in]

The length, in bytes, of the AuthenticationInformation buffer.

LocalGroups [in, optional]

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.

SourceContext [in]

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.

ProfileBuffer [out]

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.

ValueMeaning
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.

ProfileBufferLength [out]

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

LogonId [out]

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.

Token [out]

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.

Quotas [out]

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.

SubStatus [out]

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.

ValueMeaning
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.

ValueDescription
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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Ntsecapi.h

Library

Secur32.lib

DLL

Secur32.dll

See also

Allowing Anonymous Access
LsaCallAuthenticationPackage
LsaFreeReturnBuffer
LsaLookupAuthenticationPackage

 

 

Community Additions

ADD
Show:
© 2014 Microsoft