The LogonUser function attempts to log a user on to the local computer. The local computer is the computer from which LogonUser was called. You cannot use LogonUser to log on to a remote computer. You specify the user with a user name and domain and authenticate the user with a plaintext password. If the function succeeds, you receive a handle to a token that represents the logged-on user. You can then use this token handle to impersonate the specified user or, in most cases, to create a process that runs in the context of the specified user.
Syntax
Parameters
- lpszUsername [in]
-
A pointer to a null-terminated string that specifies the name of the user. This is the name of the user account to log on to. If you use the user principal name (UPN) format, User@DNSDomainName, the lpszDomain parameter must be NULL.
- lpszDomain [in, optional]
-
A pointer to a null-terminated string that specifies the name of the domain or server whose account database contains the lpszUsername account. If this parameter is NULL, the user name must be specified in UPN format. If this parameter is ".", the function validates the account by using only the local account database.
- lpszPassword [in]
-
A pointer to a null-terminated string that specifies the plaintext password for the user account specified by lpszUsername. When you have finished using the password, clear the password from memory by calling the SecureZeroMemory function. For more information about protecting passwords, see Handling Passwords.
- dwLogonType [in]
-
The type of logon operation to perform. This parameter can be one of the following values, defined in Winbase.h.
Value Meaning - LOGON32_LOGON_BATCH
This logon type is intended for batch servers, where processes may be executing on behalf of a user without their direct intervention. This type is also for higher performance servers that process many plaintext authentication attempts at a time, such as mail or Web servers. The LogonUser function does not cache credentials for this logon type.
- LOGON32_LOGON_INTERACTIVE
This logon type is intended for users who will be interactively using the computer, such as a user being logged on by a terminal server, remote shell, or similar process. This logon type has the additional expense of caching logon information for disconnected operations; therefore, it is inappropriate for some client/server applications, such as a mail server.
- LOGON32_LOGON_NETWORK
This logon type is intended for high performance servers to authenticate plaintext passwords. The LogonUser function does not cache credentials for this logon type.
- LOGON32_LOGON_NETWORK_CLEARTEXT
This logon type preserves the name and password in the authentication package, which allows the server to make connections to other network servers while impersonating the client. A server can accept plaintext credentials from a client, call LogonUser, verify that the user can access the system across the network, and still communicate with other servers.
- LOGON32_LOGON_NEW_CREDENTIALS
This logon type allows the caller to clone its current token and specify new credentials for outbound connections. The new logon session has the same local identifier but uses different credentials for other network connections.
This logon type is supported only by the LOGON32_PROVIDER_WINNT50 logon provider.
- LOGON32_LOGON_SERVICE
Indicates a service-type logon. The account provided must have the service privilege enabled.
- LOGON32_LOGON_UNLOCK
This logon type is for GINA DLLs that log on users who will be interactively using the computer. This logon type can generate a unique audit record that shows when the workstation was unlocked.
- dwLogonProvider [in]
-
Specifies the logon provider. This parameter can be one of the following values.
Value Meaning - LOGON32_PROVIDER_DEFAULT
Use the standard logon provider for the system. The default security provider is negotiate, unless you pass NULL for the domain name and the user name is not in UPN format. In this case, the default provider is NTLM.
Windows 2000: The default security provider is NTLM.- LOGON32_PROVIDER_WINNT50
Use the negotiate logon provider.
- LOGON32_PROVIDER_WINNT40
Use the NTLM logon provider.
- phToken [out]
-
A pointer to a handle variable that receives a handle to a token that represents the specified user.
You can use the returned handle in calls to the ImpersonateLoggedOnUser function.
In most cases, the returned handle is a primary token that you can use in calls to the CreateProcessAsUser function. However, if you specify the LOGON32_LOGON_NETWORK flag, LogonUser returns an impersonation token that you cannot use in CreateProcessAsUser unless you call DuplicateTokenEx to convert it to a primary token.
When you no longer need this handle, close it by calling the CloseHandle function.
Return Value
If the function succeeds, the function returns nonzero.
If the function fails, it returns zero. To get extended error information, call GetLastError.
Remarks
Windows 2000: If you need to validate credentials, use the SSPI APIs. For information about using the SSPI APIs, see How To Validate User Credentials on Microsoft Operating Systems. Use the LogonUser or LogonUserEx function if you need to impersonate the user by using the returned access token and access a resource.
The LOGON32_LOGON_NETWORK logon type is fastest, but it has the following limitations:
- The function returns an impersonation token, not a primary token. You cannot use this token directly in the CreateProcessAsUser function. However, you can call the DuplicateTokenEx function to convert the token to a primary token, and then use it in CreateProcessAsUser.
- If you convert the token to a primary token and use it in CreateProcessAsUser to start a process, the new process cannot access other network resources, such as remote servers or printers, through the redirector. An exception is that if the network resource is not access controlled, then the new process will be able to access it.
The SE_TCB_NAME privilege is not required for this function unless you are logging onto a Passport account.
Windows 2000: The process calling LogonUser requires the SE_TCB_NAME privilege. If the calling process does not have this privilege, LogonUser fails and GetLastError returns ERROR_PRIVILEGE_NOT_HELD. In some cases, the process that calls LogonUser must also have the SE_CHANGE_NOTIFY_NAME privilege enabled; otherwise, LogonUser fails and GetLastError returns ERROR_ACCESS_DENIED. This privilege is not required for the local system account or accounts that are members of the administrators group. By default, SE_CHANGE_NOTIFY_NAME is enabled for all users, but some administrators may disable it for everyone. For more information about privileges, see Privileges.
The account specified by lpszUsername, must have the necessary account rights. For example, to log on a user with the LOGON32_LOGON_INTERACTIVE flag, the user (or a group to which the user belongs) must have the SE_INTERACTIVE_LOGON_NAME account right. For a list of the account rights that affect the various logon operations, see Account Rights Constants.
A user is considered logged on if at least one token exists. If you call CreateProcessAsUser and then close the token, the system considers the user as still logged on until the process (and all child processes) have ended.
If the LogonUser call is successful, the system notifies network providers that the logon occurred by calling the provider's NPLogonNotify entry-point function.
Requirements
|
Minimum supported client |
Windows 2000 Professional |
|---|---|
|
Minimum supported server |
Windows 2000 Server |
|
Header |
Winbase.h (include Windows.h) |
|
Library |
Advapi32.lib |
|
DLL |
Advapi32.dll |
|
Unicode and ANSI names |
LogonUserW (Unicode) and LogonUserA (ANSI) |
See Also
- Client/Server Access Control
- Client/Server Access Control Functions
- CloseHandle
- CreateProcessAsUser
- DuplicateTokenEx
- ImpersonateLoggedOnUser
- Client/Server Access Control Functions
Send comments about this topic to Microsoft
Build date: 4/6/2010