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。
[in] OriginName
一个标识登录尝试来源的字符串。 有关详细信息,请参阅“备注”。
[in] LogonType
SECURITY_LOGON_TYPE 枚举的值,该值指定所请求的登录类型。 如果 LogonType 是 Interactive 或 Batch,则会生成一个主令牌来表示新用户。 如果 LogonType 为 Network,则会生成模拟令牌。
[in] AuthenticationPackage
用于身份验证的身份验证包的标识符。 可以通过调用 LsaLookupAuthenticationPackage 来获取此值。
[in] AuthenticationInformation
指向包含身份验证信息(如用户名和密码)的输入缓冲区的指针。 此缓冲区的格式和内容由身份验证包确定。
此参数可以是 MSV1_0 和 Kerberos 身份验证包的以下输入缓冲区结构之一。
值 | 含义 |
---|---|
|
对交互式用户登录进行身份验证。
MSV1_0_INTERACTIVE_LOGON 结构的 LogonDomainName、UserName 和 Password 成员必须指向内存中与结构本身连续的缓冲区。 AuthenticationInformationLength 参数的值必须考虑这些缓冲区的长度。 |
|
对交互式用户登录进行身份验证。 |
|
在初始网络登录或断开连接时对用户进行身份验证。 |
|
在票证刷新时对用户进行身份验证,这是普通工作站解锁登录的变体。 |
|
使用交互式智能卡登录对用户进行身份验证。 |
|
使用服务对用户进行身份验证, (S4U) 登录。 |
|
对用户进行身份验证,以解锁在交互式智能卡登录会话期间锁定的工作站。 |
|
使用 LOGON32_PROVIDER_WINNT50 或 LOGON32_PROVIDER_DEFAULT 对用户智能登录卡进行身份验证。 |
|
对用户进行身份验证,以解锁在智能卡登录会话期间锁定的工作站。 |
|
使用 S4U 客户端请求对用户进行身份验证。 对于 约束委派,如果客户端使用 LSA 模式身份验证包登录,则不需要调用 LsaLogonUser。 在 Windows 操作系统上,其中包括 Kerberos、 NTLM、 安全通道和 摘要。 要使此调用成功,必须满足以下条件:
|
|
处理 NTLM 2.0 协议登录的后半部分。 此类型登录的前半部分是通过使用MsV1_0Lm20ChallengeRequest消息调用 LsaCallAuthenticationPackage 来执行 的 。 有关详细信息,请参阅 MSV1_0_PROTOCOL_MESSAGE_TYPE 中MsV1_0Lm20ChallengeRequest的说明。
这种类型的登录可以使用子身份验证包。 |
|
使用子身份验证对用户进行身份验证。 |
有关其他身份验证包使用的缓冲区的详细信息,请参阅这些身份验证包的文档。
[in] AuthenticationInformationLength
AuthenticationInformation 缓冲区的长度(以字节为单位)。
[in, optional] LocalGroups
要添加到经过身份验证的用户的令牌的其他组标识符的列表。 将添加这些组标识符,以及默认组 WORLD 和登录类型组 (Interactive、Batch 或 Network) ,这些标识符会自动包含在每个用户令牌中。
[in] SourceContext
一个TOKEN_SOURCE结构,用于标识源模块(例如会话管理器)以及可能对该模块有用的上下文。 此信息包含在用户令牌中,可以通过调用 GetTokenInformation 进行检索。
[out] ProfileBuffer
指向 void 指针的指针,该指针接收包含身份验证信息(例如登录 shell 和主目录)的输出缓冲区的地址。
此参数可以是 MSV1_0 和 Kerberos 身份验证包的以下输出缓冲区结构之一。
有关其他身份验证包使用的缓冲区的详细信息,请参阅该身份验证包的文档。
如果不再需要此缓冲区,调用应用程序必须通过调用 LsaFreeReturnBuffer 函数来释放此缓冲区。
[out] ProfileBufferLength
指向 ULONG 的指针,该 ULONG 接收返回的配置文件缓冲区的长度(以字节为单位)。
[out] LogonId
指向接收唯一标识登录会话的 LUID 的缓冲区的指针。 此 LUID 由对登录信息进行身份验证的域控制器分配。
[out] Token
指向句柄的指针,该句柄接收为此会话创建的新用户令牌。 使用完令牌后,通过调用 CloseHandle 函数将其释放。
[out] Quotas
返回主令牌时,此参数接收 QUOTA_LIMITS 结构,该结构包含分配给新登录用户的初始进程的进程配额限制。
[out] SubStatus
如果登录因帐户限制而失败,此参数将接收有关登录失败原因的信息。 仅当用户的帐户信息有效且拒绝登录时,才会设置此值。
此参数可以是MSV1_0身份验证包的下列 SubStatus 值之一。
值 | 含义 |
---|---|
|
用户帐户有时间限制,目前不能用于登录。 |
|
用户帐户有工作站限制,不能用于从当前工作站登录。 |
|
用户帐户密码已过期。 |
|
用户帐户当前已禁用,不能用于登录。 |
返回值
如果函数成功,该函数将返回STATUS_SUCCESS。
如果该函数失败,它将返回 NTSTATUS 代码,该代码可以是以下值之一。
值 | 说明 |
---|---|
|
调用方内存配额不足以分配身份验证包返回的输出缓冲区。 |
|
用户帐户和密码是合法的,但用户帐户有一个限制,此时会阻止登录。 有关详细信息,请参阅 SubStatus 参数中存储的值。 |
|
身份验证包无法识别提供的身份验证信息。 |
|
登录尝试失败。 未指定失败原因,但典型原因包括用户名拼写错误和密码拼写错误。 |
|
没有域控制器可用于为身份验证请求提供服务。 |
|
LSA 无法识别指定的身份验证包。 |
|
Kerberos 客户端收到了无效的 KDC 证书。 对于设备登录,需要严格的 KDC 验证,因此 KDC 必须具有使用“Kerberos 身份验证”模板或等效项的证书。 此外,KDC 证书可能已过期、吊销,或者客户端受到向错误服务器发送请求的活动攻击。 |
|
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 |