LogonUserExW 函数（winbase.h）

项目
11/20/2024

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

语法

BOOL LogonUserExW(
  [in]            LPCWSTR       lpszUsername,
  [in, optional]  LPCWSTR       lpszDomain,
  [in, optional]  LPCWSTR       lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

参数

[in] lpszUsername

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

[in, optional] lpszDomain

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

[in, optional] lpszPassword

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

[in] dwLogonType

要执行的登录操作的类型。此参数可以是下列值之一。

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

[in] dwLogonProvider

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

价值	意义
LOGON32_PROVIDER_DEFAULT	使用系统的标准登录提供程序。默认安全提供程序为 NTLM。
LOGON32_PROVIDER_WINNT50	使用协商登录提供程序。
LOGON32_PROVIDER_WINNT40	使用 NTLM 登录提供程序。

[out, optional] phToken

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

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

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

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

[out, optional] ppLogonSid

指向安全标识符（SID）的指针，该标识符接收登录用户的 SID。

使用完 SID 后，通过调用 LocalFree 函数来释放它。

[out, optional] ppProfileBuffer

指向接收包含已登录用户配置文件的缓冲区地址的指针。

[out, optional] pdwProfileLength

指向接收配置文件缓冲区长度的 DWORD 的指针。

[out, optional] pQuotaLimits

指向 QUOTA_LIMITS 结构的指针，该结构接收有关已登录用户的配额的信息。

返回值

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

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

言论

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

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

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

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

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

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

注意

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

要求

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