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
)
{...}

參數

[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的指標，接收ProfileBuffer緩衝區的長度，以位元組為單位。

[out] LogonId

LUID的指標，接收可唯一識別此登入會話的新登入識別碼。驗證套件負責配置此 LUID，並建立此登入的登入會話。

[out] SubStatus

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