共用方式為

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 取得的句柄。

只有在下列一或多個為 true 時，才需要呼叫端擁有 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、 安全通道和 摘要。 若要讓此呼叫成功，下列項目必須為 true：
  • 如果計算機是網域成員) ，則呼叫者必須是網域帳戶， (這包括LOCAL_SYSTEM。
  • 如果使用服務帳戶，該帳戶必須在本機計算機上設定 SeTcbPrivilege ，才能取得模擬令牌。 否則，會使用身分識別令牌。
  • 呼叫端必須是 Pre-Windows 2000 Compatible Access 的成員，或具有用戶端群組成員資格的讀取許可權。 Windows 授權存取群組中的成員資格保證用戶端群組成員資格的讀取許可權。 如需如何設定 Windows 授權存取群組的資訊，請參閱 Microsoft 知識庫。
KERB_S4U_LOGON結構的 ClientUpn 和 ClientRealm 成員必須指向與結構本身連續的記憶體中的緩衝區。 AuthenticationInformationLength 參數的值必須考慮這些緩衝區的長度。
MSV1_0_LM20_LOGON
MSV1_0
 處理 NTLM 2.0 通訊協定登入的後半部。 此登入類型的前半部是透過呼叫 LsaCallAuthenticationPackage 與 MsV1_0Lm20ChallengeRequest 訊息來執行。 如需詳細資訊，請參閱 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 指標的指標，接收包含驗證資訊的輸出緩衝區位址，例如登入殼層和主目錄。

此參數可以是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 的指標，接收傳回之配置檔緩衝區的長度，以位元組為單位。

[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 程式碼，它可以是下列其中一個值。

值 Description
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」 來指出終端機一或 「NTLM - remote node JAZZ」。，以表示透過稱為 「JAZZ」 的遠端節點使用 NTLM 的網路登錄。

您必須個別呼叫 LsaLogonUser ，才能更新LOCAL_SYSTEM和NETWORK_SERVICE的 PKINIT 裝置認證。 沒有 PKINIT 裝置認證時，成功的呼叫不會執行任何作業。 當有 PKINIT 裝置認證時，成功的呼叫會清除 PKINIT 裝置認證，只保留密碼認證。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 ntsecapi.h
程式庫 Secur32.lib
Dll Secur32.dll

另請參閱

允許匿名存取

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage