LogonUserA 函数 (winbase.h)

  • 项目

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) 格式 为 User@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。 此登录类型可以生成唯一的审核记录，用于显示工作站何时解锁。

[in] dwLogonProvider

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

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

[out] phToken

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

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

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

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

返回值

如果函数成功，则函数返回非零值。

如果函数失败，则返回零。 要获得更多的错误信息，请调用 GetLastError。

注解

LOGON32_LOGON_NETWORK登录类型最快，但它具有以下限制：

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

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

由 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 [仅限桌面应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

客户端/服务器访问控制

客户端/服务器访问控制函数

CloseHandle

CreateProcessAsUser

DuplicateTokenEx

ImpersonateLoggedOnUser