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.

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

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.

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.

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.

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

See also

Allowing Anonymous Access

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage