LogonUserW 函式 (winbase.h)

發行項
03/08/2023

LogonUser函式會嘗試將使用者登入本機電腦。本機電腦是 呼叫 LogonUser 的電腦。您無法使用 LogonUser 登入遠端電腦。您可以使用使用者名稱和網域指定使用者，並使用純文字密碼驗證使用者。如果函式成功，您會收到代表登入使用者的權杖控制碼。然後，您可以使用此權杖控制碼來模擬指定的使用者，或在大多數情況下，建立在指定使用者內容中執行的進程。

語法

BOOL LogonUserW(
  [in]           LPCWSTR lpszUsername,
  [in, optional] LPCWSTR lpszDomain,
  [in, optional] LPCWSTR lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

參數

[in] lpszUsername

指定使用者名稱之 Null 終止字串的指標。這是要登入的使用者帳戶名稱。如果您使用使用者主體名稱 (UPN) 格式，則@lpszDomain參數必須是Null。

[in, optional] lpszDomain

Null 終止字串的指標，指定帳戶資料庫包含 lpszUsername 帳戶之網域或伺服器的名稱。如果此參數為 Null，則必須以 UPN 格式指定使用者名稱。如果此參數為「.」，則函式只會使用本機帳戶資料庫來驗證帳戶。

[in, optional] lpszPassword

Null 終止字串的指標，指定 lpszUsername所指定使用者帳戶的純文字密碼。當您完成使用密碼時，請呼叫 SecureZeroMemory 函式，從記憶體清除密碼。如需保護密碼的詳細資訊，請參閱處理密碼。

[in] dwLogonType

要執行的登入作業類型。此參數可以是下列其中一個值，定義于 Winbase.h 中。

值	意義
LOGON32_LOGON_BATCH	此登入類型適用于批次伺服器，其中進程可能會代表使用者執行，而不需直接介入。此類型也適用于一次處理許多純文字驗證嘗試的高效能伺服器，例如郵件或網頁伺服器。
LOGON32_LOGON_INTERACTIVE	此登入類型適用于以互動方式使用電腦的使用者，例如由終端機伺服器、遠端殼層或類似程式登入的使用者。此登入類型有快取已中斷連線作業之登入資訊的額外費用;因此，某些用戶端/伺服器應用程式不適當，例如郵件伺服器。
LOGON32_LOGON_NETWORK	此登入類型適用于高效能伺服器來驗證純文字密碼。 LogonUser函式不會快取此登入類型的認證。
LOGON32_LOGON_NETWORK_CLEARTEXT	此登入類型會保留驗證套件中的名稱和密碼，這可讓伺服器在模擬用戶端時連線到其他網路伺服器。伺服器可以接受來自用戶端的純文字認證、呼叫 LogonUser、確認使用者可以跨網路存取系統，但仍與其他伺服器通訊。
LOGON32_LOGON_NEW_CREDENTIALS	此登入類型可讓呼叫端複製其目前權杖，並指定輸出連線的新認證。新的登入會話具有相同的本機識別碼，但會針對其他網路連線使用不同的認證。只有LOGON32_PROVIDER_WINNT50登入提供者才支援此登入類型。注意：自 2023 年 1 月起，無法使用群組受控服務帳戶LOGON32_LOGON_NEW_CREDENTIALS登入類型， (gMSA) 。
LOGON32_LOGON_SERVICE	表示服務類型登入。提供的帳戶必須啟用服務許可權。
LOGON32_LOGON_UNLOCK	不再支援 GINA。 Windows Server 2003 和 Windows XP：此登入類型適用于以互動方式使用電腦登入使用者的 GINA DLL。此登入類型可以產生唯一的稽核記錄，顯示工作站解除鎖定時。

[in] dwLogonProvider

指定登入提供者。此參數可以是下列其中一個值。

值	意義
LOGON32_PROVIDER_DEFAULT	使用系統的標準登入提供者。除非您為功能變數名稱傳遞Null，而且使用者名稱不是 UPN 格式，否則預設安全性提供者會交涉。在此情況下，預設提供者為 NTLM。
LOGON32_PROVIDER_WINNT50	使用交涉登入提供者。
LOGON32_PROVIDER_WINNT40	使用 NTLM 登入提供者。

[out] phToken

控制碼變數的指標，可接收代表指定之使用者的權杖控制碼。

您可以在對 ImpersonateLoggedOnUser 函式的呼叫中使用傳回的控制碼。

在大部分情況下，傳回的控制碼是可在呼叫 CreateProcessAsUser函式時使用的主要權杖。不過，如果您指定LOGON32_LOGON_NETWORK旗標，LogonUser會傳回您無法在CreateProcessAsUser中使用的模擬權杖，除非您呼叫DuplicateTokenEx將它轉換成主要權杖。

當您不再需要此控制碼時，請呼叫 CloseHandle 函式加以關閉。

傳回值

如果函式成功，函式會傳回非零。

如果函式失敗，它會傳回零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

LOGON32_LOGON_NETWORK登入類型最快，但有下列限制：

函式會傳回模擬權杖，而不是主要權杖。您無法直接在 CreateProcessAsUser 函式中使用此權杖。不過，您可以呼叫 DuplicateTokenEx 函式，將權杖轉換成主要權杖，然後在 CreateProcessAsUser中使用。
如果您將權杖轉換成主要權杖，並在 CreateProcessAsUser 中使用它來啟動程式，則新進程無法透過重新導向器存取其他網路資源，例如遠端伺服器或印表機。例外狀況是，如果網路資源不受存取控制，則新進程將能夠存取它。

除非您登入 Passport 帳戶，否則此函式不需要SE_TCB_NAME許可權。

lpszUsername指定的帳號必須具有必要的帳戶許可權。例如，若要使用LOGON32_LOGON_INTERACTIVE旗標登入使用者，使用者 (或使用者) 所屬的群組必須擁有SE_INTERACTIVE_LOGON_NAME帳戶許可權。如需影響各種登入作業的帳戶許可權清單，請參閱帳戶許可權常數。

如果至少有一個權杖存在，則會將使用者視為登入。如果您呼叫 CreateProcessAsUser ，然後關閉權杖，系統會將使用者視為仍登入，直到進程 (和所有子進程) 結束為止。

如果 LogonUser 呼叫成功，系統會透過呼叫提供者的 NPLogonNotify 進入點函式來通知網路提供者登入。

範例

您可以使用下列程式碼來產生 LocalService 權杖。

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

注意

winbase.h 標頭會將 LogonUser 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Advapi32.lib
DLL	Advapi32.dll