LSA_AP_LOGON_USER回调函数 (ntsecpkg.h)

项目
08/25/2023

对用户的登录凭据进行身份验证。

仅针对用户的初始登录调用此函数。后续身份验证请求必须使用 LsaCallAuthenticationPackage。

如果 LsaApLogonUser 成功，它将创建登录会话。它还返回用于生成表示新登录用户的令牌的信息。

语法

LSA_AP_LOGON_USER LsaApLogonUser;

NTSTATUS LsaApLogonUser(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID AuthenticationInformation,
  [in]  PVOID ClientAuthenticationBase,
  [in]  ULONG AuthenticationInformationLength,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferLength,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PLSA_UNICODE_STRING *AccountName,
  [out] PLSA_UNICODE_STRING *AuthenticatingAuthority
)
{...}

parameters

[in] ClientRequest

指向表示 LSA 客户端请求的不透明 LSA_CLIENT_REQUEST 缓冲区的指针。身份验证包可以将此值传递到 AllocateClientBuffer 和 FreeClientBuffer 中，以标识应在其中分配或释放内存的客户端进程。

[in] LogonType

标识所请求登录类型的 SECURITY_LOGON_TYPE 值。

[in] AuthenticationInformation

提供特定于身份验证包的身份验证信息。 LSA 将释放此缓冲区。这是传入 LsaLogonUser 的相同输入缓冲区。

[in] ClientAuthenticationBase

提供客户端进程中身份验证信息的地址。可能需要重新映射 AuthenticationInformation 缓冲区中的任何指针。

[in] AuthenticationInformationLength

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

[out] ProfileBuffer

在客户端进程中接收配置文件缓冲区地址的指针。身份验证包负责通过调用 AllocateClientBuffer 函数在客户端进程中分配 ProfileBuffer 缓冲区。但是，如果 LSA 随后遇到阻止成功登录的错误，则 LSA 将释放此缓冲区。

此缓冲区的内容由身份验证包确定。 LSA 不会更改此缓冲区;它只是将值返回到 LsaLogonUser 函数。

[out] ProfileBufferLength

指向 ULONG 的指针，该 ULONG 接收 ProfileBuffer 缓冲区的长度（以字节为单位）。

[out] LogonId

指向接收唯一标识此登录会话的新登录 ID 的 LUID 的指针。身份验证包负责分配此 LUID，并为此登录创建登录会话。

[out] SubStatus

指向 NTSTATUS 的指针，该 NTSTATUS 接收由于帐户限制而失败的原因。 SubStatus 中返回的值由身份验证包确定。

下表列出了 MSV1_0 和 Kerberos 身份验证包的 SubStatus 值。

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

有关 NTSTATUS 代码的详细信息，请参阅平台 SDK 随附的 Subauth.h 头文件。

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

[out] TokenInformationType

一个指针，用于接收 LSA_TOKEN_INFORMATION_TYPE 值的地址，该值指示要包含在要创建的令牌中返回的信息的类型。此信息在 TokenInformation 缓冲区中返回。

[out] TokenInformation

接收要包含在令牌中的信息的指针。 TokenInformation 缓冲区的格式和内容由 TokenInformationType 参数指示。身份验证包负责分配 TokenInformation 使用的内存;但是，此内存将由 LSA 释放。

[out] AccountName

指向接收用户帐户名称的LSA_UNICODE_STRING 结构的指针。无论调用是成功还是失败，都必须始终返回 AccountName;其字符串包含在身份验证尝试的审核记录中。身份验证包负责分配 AccountName 使用的内存;但是，此内存将由 LSA 释放。

[out] AuthenticatingAuthority

可选。指向 LSA_UNICODE_STRING 结构的指针，该结构接收登录的身份验证机构的说明。此参数可以为 NULL。此字符串包含在身份验证尝试的审核记录中。身份验证包负责分配 AuthenticatingAuthority 使用的内存;但是，此内存将由 LSA 释放。

MSV1_0身份验证包返回验证帐户的域的域名。 Kerberos 身份验证包返回 NetBIOS 域名。

返回值

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

如果函数失败，它应返回 NTSTATUS 错误代码，可以是以下值之一或 LSA 策略函数返回值之一。

返回代码	说明
STATUS_NO_MEMORY	无法完成登录，因为客户端的内存配额不足以分配返回缓冲区。
STATUS_NO_LOGON_SERVERS	没有域控制器可用于为身份验证请求提供服务。
STATUS_LOGON_FAILURE	登录尝试失败。未指定失败的原因;典型原因包括用户名和密码拼写错误。
STATUS_ACCOUNT_RESTRICTION	用户帐户和密码是合法的，但用户帐户限制此时会阻止登录。有关其他信息，请参阅 SubStatus 参数。
STATUS_BAD_VALIDATION_CLASS	指定的身份验证包无法识别提供的身份验证信息。

调用应用程序可以使用 LsaNtStatusToWinError 函数将 NTSTATUS 代码转换为 Windows 错误代码。

注解

身份验证包必须实现以下函数之一： LsaApLogonUser、 LsaApLogonUserEx 或 LsaApLogonUserEx2。

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	ntsecpkg.h