logonUserExA 函数 (winbase.h)

项目
08/27/2023

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

语法

BOOL LogonUserExA(
  [in]            LPCSTR        lpszUsername,
  [in, optional]  LPCSTR        lpszDomain,
  [in, optional]  LPCSTR        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。此登录类型可以生成唯一的审核记录，用于显示工作站何时解锁。

[in] dwLogonProvider

登录提供程序。此参数的取值可为下列值之一：

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

[out, optional] phToken

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

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

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

如果不再需要此句柄，请通过调用 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 中使用它来启动进程，则新进程无法通过重定向程序访问其他网络资源，如远程服务器或打印机。例外情况是，如果网络资源不受访问控制，则新进程将能够访问它。

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

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

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

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

注意

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

要求

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