Windows API Documentation
LogonUser
BOOL LogonUserA(
_In_ LPCSTR lpszUsername,
_In_opt_ LPCSTR lpszDomain,
_In_opt_ LPCSTR lpszPassword,
_In_ DWORD dwLogonType,
_In_ DWORD dwLogonProvider,
_Out_ PHANDLE phToken
);
BOOL LogonUserW(
_In_ LPCWSTR lpszUsername,
_In_opt_ LPCWSTR lpszDomain,
_In_opt_ LPCWSTR lpszPassword,
_In_ DWORD dwLogonType,
_In_ DWORD dwLogonProvider,
_Out_ PHANDLE phToken
);
The LogonUser function (LogonUserA for ANSI and LogonUserW for Unicode) attempts to log on the specified user account. This function is suitable for use with the client/server model and can be used to authenticate a user in a client/server application.
Parameters
| Parameter | Description |
|---|---|
lpszUsername |
A pointer to a null-terminated string that specifies the name of the user for whom to log on. This name can be in the user principal name (UPN) format (e.g., username@example.com) or the classic domain name format (e.g., DOMAIN\username).
|
lpszDomain |
A pointer to a null-terminated string that specifies the domain name. This string can be in UPN format or classic domain name format. If this parameter is NULL, the function attempts to log on using the primary domain of the local computer. |
lpszPassword |
A pointer to a null-terminated string that specifies the plaintext password for the user account specified by lpszUsername.
The password is passed in clear text. Do not use this function for applications that require high security. Consider using DPAPI (Data Protection API) for password encryption.
|
dwLogonType |
The type of logon. This parameter can be one of the following values:
|
dwLogonProvider |
The logon provider. This parameter can be one of the following values:
LOGON32_PROVIDER_DEFAULT to allow the system to choose the best logon provider.
|
phToken |
A pointer to a variable that receives a handle to a access token that can be used to impersonate a specific user. The handle contains the user's security information.
The caller must call the CloseHandle function to close the returned handle when it is no longer needed.
|
Return Value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The LogonUser function creates an access token for the specified user and returns a handle to it. This access token can then be used to impersonate the user in any process.
When you are finished impersonating the user, call the CloseHandle function to close the token handle.
If the specified user account is a local user account, the lpszDomain parameter should be NULL.
The LogonUser function requires that the user account exist and be valid. It does not create new accounts.
Logon Types
The following logon types are supported:
LOGON32_LOGON_INTERACTIVE: Use this logon type to log on a user interactively.LOGON32_LOGON_NETWORK: Use this logon type to log on a user for network access.LOGON32_LOGON_BATCH: Use this logon type for batch server authentication.LOGON32_LOGON_SERVICE: Use this logon type to log on a user account that is started as a service. The account's password must be known.LOGON32_LOGON_UNLOCK: Use this logon type to unlock a workstation that is locked.
Logon Providers
The following logon providers are supported:
LOGON32_PROVIDER_DEFAULT: Use this value to use theNT LM Security Support Provider.LOGON32_PROVIDER_LM_INTERACTIVE: Use this value to use the interactive logon functionality of the NT LM Security Support Provider.LOGON32_PROVIDER_LM_NETAPI: Use this value to use the network logon functionality of the NT LM Security Support Provider.LOGON32_PROVIDER_WINNT35: Use this value to use the NT LAN Manager (NTLM) authentication package.LOGON32_PROVIDER_WINNT40: Use this value to use the NTLM authentication package with the security service provider interface (SSPI).
See Also
Example
The following C++ code demonstrates how to use the LogonUser function.
#include <windows.h>
#include <iostream>
int main() {
HANDLE hToken;
LPCSTR username = "YourUsername"; // Replace with the actual username
LPCSTR domain = "YourDomain"; // Replace with the actual domain or NULL for local
LPCSTR password = "YourPassword"; // Replace with the actual password
// Attempt to log on with interactive logon type and default provider
if (LogonUserA(username, domain, password, LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, &hToken)) {
std::cout << "Logon successful. Token handle obtained." << std::endl;
// Use the token for impersonation or other security operations
// ...
// Close the token handle when done
CloseHandle(hToken);
std::cout << "Token handle closed." << std::endl;
} else {
DWORD error = GetLastError();
std::cerr << "Logon failed. Error code: " << error << std::endl;
// You can use FormatMessage to get a human-readable error string
}
return 0;
}