LsaLogonUser 函数 (ntsecapi.h)

  • 项目

LsaLogonUser 函数使用存储的凭据信息对安全主体的登录数据进行身份验证。

如果身份验证成功，此函数将创建新的登录会话并返回用户令牌。

使用新证书凭据获取授予票证 (TGT) 的新票证时，将清除系统的所有 TGT 和服务票证。 属于复合标识的任何用户服务票证也会被清除。

语法

NTSTATUS LsaLogonUser(
  [in]           HANDLE              LsaHandle,
  [in]           PLSA_STRING         OriginName,
  [in]           SECURITY_LOGON_TYPE LogonType,
  [in]           ULONG               AuthenticationPackage,
  [in]           PVOID               AuthenticationInformation,
  [in]           ULONG               AuthenticationInformationLength,
  [in, optional] PTOKEN_GROUPS       LocalGroups,
  [in]           PTOKEN_SOURCE       SourceContext,
  [out]          PVOID               *ProfileBuffer,
  [out]          PULONG              ProfileBufferLength,
  [out]          PLUID               LogonId,
  [out]          PHANDLE             Token,
  [out]          PQUOTA_LIMITS       Quotas,
  [out]          PNTSTATUS           SubStatus
);

参数

[in] LsaHandle

从上一次调用 LsaRegisterLogonProcess 获取的句柄。

仅当满足以下一项或多项条件时，调用方才需要具有 SeTcbPrivilege ：

  • 使用子身份验证包。
  • 使用KERB_S4U_LOGON ，调用方请求模拟令牌。
  • LocalGroups 参数不为 NULL。
如果不需要 SeTcbPrivilege ，请调用 LsaConnectUntrusted 以获取句柄。

[in] OriginName

一个标识登录尝试来源的字符串。 有关详细信息，请参阅“备注”。

[in] LogonType

SECURITY_LOGON_TYPE 枚举的值，该值指定所请求的登录类型。 如果 LogonType 是 Interactive 或 Batch，则会生成一个主令牌来表示新用户。 如果 LogonType 为 Network，则会生成模拟令牌。

[in] AuthenticationPackage

用于身份验证的身份验证包的标识符。 可以通过调用 LsaLookupAuthenticationPackage 来获取此值。

[in] AuthenticationInformation

指向包含身份验证信息（如用户名和密码）的输入缓冲区的指针。 此缓冲区的格式和内容由身份验证包确定。

此参数可以是 MSV1_0 和 Kerberos 身份验证包的以下输入缓冲区结构之一。

值 含义
MSV1_0_INTERACTIVE_LOGON
MSV1_0
 对交互式用户登录进行身份验证。

MSV1_0_INTERACTIVE_LOGON 结构的 LogonDomainName、UserName 和 Password 成员必须指向内存中与结构本身连续的缓冲区。 AuthenticationInformationLength 参数的值必须考虑这些缓冲区的长度。
KERB_INTERACTIVE_LOGON
Kerberos
 对交互式用户登录进行身份验证。
KERB_TICKET_LOGON
Kerberos
 在初始网络登录或断开连接时对用户进行身份验证。
KERB_TICKET_UNLOCK_LOGON
Kerberos
 在票证刷新时对用户进行身份验证，这是普通工作站解锁登录的变体。
KERB_CERTIFICATE_LOGON
Kerberos
 使用交互式智能卡登录对用户进行身份验证。
KERB_CERTIFICATE_S4U_LOGON
Kerberos
 使用服务对用户进行身份验证， (S4U) 登录。
KERB_CERTIFICATE_UNLOCK_LOGON
Kerberos
 对用户进行身份验证，以解锁在交互式智能卡登录会话期间锁定的工作站。
KERB_SMARTCARD_LOGON
Kerberos
 使用 LOGON32_PROVIDER_WINNT50 或 LOGON32_PROVIDER_DEFAULT 对用户智能登录卡进行身份验证。
KERB_SMARTCARD_UNLOCK_LOGON
Kerberos
 对用户进行身份验证，以解锁在智能卡登录会话期间锁定的工作站。
KERB_S4U_LOGON
Kerberos
 使用 S4U 客户端请求对用户进行身份验证。 对于 约束委派，如果客户端使用 LSA 模式身份验证包登录，则不需要调用 LsaLogonUser。 在 Windows 操作系统上，其中包括 Kerberos、 NTLM、 安全通道和 摘要。 要使此调用成功，必须满足以下条件：
  • 如果计算机是域成员) ，则调用方必须是域帐户， (这包括LOCAL_SYSTEM。
  • 如果使用服务帐户，则帐户必须在本地计算机上设置 SeTcbPrivilege 才能获取模拟令牌。 否则，将使用标识令牌。
  • 调用方必须是 Windows 2000 前兼容访问 的成员，或者对客户端的组成员身份具有读取访问权限。 Windows 授权访问组中的成员身份保证对客户端的组成员身份的读取访问权限。 有关如何配置 Windows 授权访问组的信息，请参阅 Microsoft 知识库。
KERB_S4U_LOGON 结构的 ClientUpn 和 ClientRealm 成员必须指向内存中与结构本身连续的缓冲区。 AuthenticationInformationLength 参数的值必须考虑这些缓冲区的长度。
MSV1_0_LM20_LOGON
MSV1_0
 处理 NTLM 2.0 协议登录的后半部分。 此类型登录的前半部分是通过使用MsV1_0Lm20ChallengeRequest消息调用 LsaCallAuthenticationPackage 来执行 的 。 有关详细信息，请参阅 MSV1_0_PROTOCOL_MESSAGE_TYPE 中MsV1_0Lm20ChallengeRequest的说明。

这种类型的登录可以使用子身份验证包。
MSV1_0_SUBAUTH_LOGON
MSV1_0
 使用子身份验证对用户进行身份验证。
 

有关其他身份验证包使用的缓冲区的详细信息，请参阅这些身份验证包的文档。

[in] AuthenticationInformationLength

AuthenticationInformation 缓冲区的长度（以字节为单位）。

[in, optional] LocalGroups

要添加到经过身份验证的用户的令牌的其他组标识符的列表。 将添加这些组标识符，以及默认组 WORLD 和登录类型组 (Interactive、Batch 或 Network) ，这些标识符会自动包含在每个用户令牌中。

[in] SourceContext

一个TOKEN_SOURCE结构，用于标识源模块（例如会话管理器）以及可能对该模块有用的上下文。 此信息包含在用户令牌中，可以通过调用 GetTokenInformation 进行检索。

[out] ProfileBuffer

指向 void 指针的指针，该指针接收包含身份验证信息（例如登录 shell 和主目录）的输出缓冲区的地址。

此参数可以是 MSV1_0 和 Kerberos 身份验证包的以下输出缓冲区结构之一。

值 含义
MSV1_0_INTERACTIVE_PROFILE
MSV1_0
 交互式用户的登录配置文件。
KERB_TICKET_PROFILE
Kerberos
 登录、断开连接和票证刷新身份验证输出。
MSV1_0_LM20_LOGON
MSV1_0
 处理 NTLM 2.0 协议登录的后半部分时的输出。
MSV1_0_LM20_LOGON_PROFILE
MSV1_0
 使用具有子身份验证的身份验证时的输出。
 

有关其他身份验证包使用的缓冲区的详细信息，请参阅该身份验证包的文档。

如果不再需要此缓冲区，调用应用程序必须通过调用 LsaFreeReturnBuffer 函数来释放此缓冲区。

[out] ProfileBufferLength

指向 ULONG 的指针，该 ULONG 接收返回的配置文件缓冲区的长度（以字节为单位）。

[out] LogonId

指向接收唯一标识登录会话的 LUID 的缓冲区的指针。 此 LUID 由对登录信息进行身份验证的域控制器分配。

[out] Token

指向句柄的指针，该句柄接收为此会话创建的新用户令牌。 使用完令牌后，通过调用 CloseHandle 函数将其释放。

[out] Quotas

返回主令牌时，此参数接收 QUOTA_LIMITS 结构，该结构包含分配给新登录用户的初始进程的进程配额限制。

[out] SubStatus

如果登录因帐户限制而失败，此参数将接收有关登录失败原因的信息。 仅当用户的帐户信息有效且拒绝登录时，才会设置此值。

此参数可以是MSV1_0身份验证包的下列 SubStatus 值之一。

值 含义
STATUS_INVALID_LOGON_HOURS
 用户帐户有时间限制，目前不能用于登录。
STATUS_INVALID_WORKSTATION
 用户帐户有工作站限制，不能用于从当前工作站登录。
STATUS_PASSWORD_EXPIRED
 用户帐户密码已过期。
STATUS_ACCOUNT_DISABLED
 用户帐户当前已禁用，不能用于登录。

返回值

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

如果该函数失败，它将返回 NTSTATUS 代码，该代码可以是以下值之一。

值 说明
STATUS_QUOTA_EXCEEDED
 调用方内存配额不足以分配身份验证包返回的输出缓冲区。
STATUS_ACCOUNT_RESTRICTION
 用户帐户和密码是合法的，但用户帐户有一个限制，此时会阻止登录。 有关详细信息，请参阅 SubStatus 参数中存储的值。
STATUS_BAD_VALIDATION_CLASS
 身份验证包无法识别提供的身份验证信息。
STATUS_LOGON_FAILURE
 登录尝试失败。 未指定失败原因，但典型原因包括用户名拼写错误和密码拼写错误。
STATUS_NO_LOGON_SERVERS
 没有域控制器可用于为身份验证请求提供服务。
STATUS_NO_SUCH_PACKAGE
 LSA 无法识别指定的身份验证包。
STATUS_PKINIT_FAILURE
 Kerberos 客户端收到了无效的 KDC 证书。 对于设备登录，需要严格的 KDC 验证，因此 KDC 必须具有使用“Kerberos 身份验证”模板或等效项的证书。 此外，KDC 证书可能已过期、吊销，或者客户端受到向错误服务器发送请求的活动攻击。
STATUS_PKINIT_CLIENT_FAILURE
 Kerberos 客户端正在使用无效的系统证书。 对于设备登录，必须有一个 DNS 名称。 此外，系统证书可能已过期或选择错误的证书。
 

有关详细信息，请参阅 LSA 策略函数返回值。

LsaNtStatusToWinError 函数将 NTSTATUS 代码转换为 Windows 错误代码。

注解

OriginName 参数应指定有意义的信息。 例如，它可能包含“TTY1”来指示终端 1 或“NTLM - 远程节点 JAZZ”，以指示通过名为“JAZZ”的远程节点使用 NTLM 的网络登录。

必须单独调用 LsaLogonUser 才能更新LOCAL_SYSTEM和NETWORK_SERVICE的 PKINIT 设备凭据。 如果没有 PKINIT 设备凭据，则成功的调用不会执行任何操作。 当存在 PKINIT 设备凭据时，成功的调用将清理 PKINIT 设备凭据，以便仅保留密码凭据。

要求

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

另请参阅

允许匿名访问

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage