LogonUserA 函数（winbase.h）

项目
11/20/2024

LogonUser 函数尝试将用户登录到本地计算机。本地计算机是调用 LogonUser 的计算机。无法使用 LogonUser 登录到远程计算机。使用用户名和域指定用户，使用纯文本密码用户进行身份验证。如果函数成功，将收到表示已登录用户的令牌的句柄。然后，可以使用此令牌句柄模拟指定的用户，或者在大多数情况下，创建在指定用户上下文中运行的进程。

语法

BOOL LogonUserA(
  [in]           LPCSTR  lpszUsername,
  [in, optional] LPCSTR  lpszDomain,
  [in, optional] LPCSTR  lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

参数

[in] lpszUsername

指向指定用户名称的以 null 结尾的字符串的指针。这是要登录的用户帐户的名称。如果使用用户主体名称（UPN）格式，用户@DNSDomainName，lpszDomain 参数必须 NULL。

[in, optional] lpszDomain

指向以 null 结尾的字符串的指针，该字符串指定其帐户数据库包含 lpszUsername 帐户的域或服务器的名称。如果此参数 NULL，则必须以 UPN 格式指定用户名。如果此参数为“.”，则函数仅使用本地帐户数据库来验证帐户。

[in, optional] lpszPassword

指向以 null 结尾的字符串的指针，该字符串指定由 lpszUsername指定的用户帐户的纯文本密码。使用完密码后，通过调用 SecureZeroMemory 函数从内存中清除密码。有关保护密码的详细信息，请参阅处理密码。

[in] dwLogonType

要执行的登录操作的类型。此参数可以是 Winbase.h 中定义的以下值之一。

价值	意义
LOGON32_LOGON_BATCH	此登录类型适用于批处理服务器，其中进程可能代表用户执行，而无需直接干预。此类型还适用于高性能服务器，这些服务器一次处理许多纯文本身份验证尝试，例如邮件或 Web 服务器。
LOGON32_LOGON_INTERACTIVE	此登录类型适用于将以交互方式使用计算机的用户，例如终端服务器、远程 shell 或类似进程登录的用户。此登录类型需要为断开连接的操作缓存登录信息的额外费用;因此，它不适用于某些客户端/服务器应用程序，例如邮件服务器。
LOGON32_LOGON_NETWORK	此登录类型适用于高性能服务器，用于对纯文本密码进行身份验证。 LogonUser 函数不缓存此登录类型的凭据。
LOGON32_LOGON_NETWORK_CLEARTEXT	此登录类型将保留身份验证包中的名称和密码，这样服务器就可以在模拟客户端时连接到其他网络服务器。服务器可以接受来自客户端的纯文本凭据，调用 LogonUser，验证用户是否可以跨网络访问系统，并且仍与其他服务器通信。
LOGON32_LOGON_NEW_CREDENTIALS	此登录类型允许调用方克隆其当前令牌，并为出站连接指定新凭据。新的登录会话具有相同的本地标识符，但对其他网络连接使用不同的凭据。此登录类型仅受LOGON32_PROVIDER_WINNT50登录提供程序支持。注意：自 2023 年 1 月起，无法将LOGON32_LOGON_NEW_CREDENTIALS登录类型与组托管服务帐户（gMSA）配合使用。
LOGON32_LOGON_SERVICE	指示服务类型登录。提供的帐户必须启用服务特权。
LOGON32_LOGON_UNLOCK	不再支持 GINA。 Windows Server 2003 和 Windows XP：此登录类型适用于 GINA DLL，这些 DLL 用于以交互方式使用计算机登录的用户。此登录类型可以生成唯一的审核记录，该记录显示工作站解锁的时间。

[in] dwLogonProvider

指定登录提供程序。此参数可以是下列值之一。

价值	意义
LOGON32_PROVIDER_DEFAULT	使用系统的标准登录提供程序。默认安全提供程序是协商的，除非为域名传递 NULL，并且用户名不采用 UPN 格式。在这种情况下，默认提供程序为 NTLM。
LOGON32_PROVIDER_WINNT50	使用协商登录提供程序。
LOGON32_PROVIDER_WINNT40	使用 NTLM 登录提供程序。

[out] phToken

指向句柄变量的指针，该变量接收表示指定用户的令牌的句柄。

可以在调用 ImpersonateLoggedOnUser 函数时使用返回的句柄。

在大多数情况下，返回的句柄是一个主令牌，可用于调用 CreateProcessAsUser 函数。但是，如果指定LOGON32_LOGON_NETWORK标志，LogonUser 将返回模拟令牌，除非调用 DuplicateTokenEx 将其转换为主令牌，否则无法在 CreateProcessAsUser 中使用。

如果不再需要此句柄，请通过调用 CloseHandle 函数将其关闭。

返回值

如果函数成功，该函数将返回非零。

如果函数失败，则返回零。若要获取扩展的错误信息，请调用 GetLastError。

言论

LOGON32_LOGON_NETWORK登录类型最快，但存在以下限制：

该函数返回模拟令牌，而不是主令牌。不能直接在 CreateProcessAsUser 函数中使用此令牌。但是，可以调用 DuplicateTokenEx 函数将令牌转换为主令牌，然后在 createProcessAsUser使用它。
如果将令牌转换为主令牌并将其用于 CreateProcessAsUser 启动进程，则新进程无法通过重定向程序访问其他网络资源，例如远程服务器或打印机。例外情况是，如果网络资源不受访问控制，则新进程将能够访问它。

除非登录到 Passport 帐户，否则此函数不需要SE_TCB_NAME特权。

由 lpszUsername指定的帐户必须具有必要的帐户权限。例如，若要使用LOGON32_LOGON_INTERACTIVE标志登录用户，用户（或用户所属的组）必须具有SE_INTERACTIVE_LOGON_NAME帐户权限。有关影响各种登录操作的帐户权限的列表，请参阅帐户权限常量。

如果至少有一个令牌存在，则认为用户已登录。如果调用 CreateProcessAsUser，然后关闭令牌，系统会将用户视为仍在登录，直到进程（以及所有子进程）结束。

如果 LogonUser 调用成功，系统会通过调用提供程序的 NPLogonNotify 入口点函数通知网络提供程序登录。

例子

可以使用以下代码生成 LocalService 令牌。

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

注意

winbase.h 标头将 LogonUser 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows Server 2003 [仅限桌面应用]
目标平台	窗户
标头	winbase.h （包括 Windows.h）
库	Advapi32.lib
DLL	Advapi32.dll