LogonUserExExW 函式
LogonUserExW函式會嘗試將使用者登入本機電腦。 本機電腦是 呼叫 LogonUserExExW 的電腦。 您無法使用 LogonUserExW 登入遠端電腦。 使用使用者名稱和網域來指定使用者，並使用純文字密碼 來驗證 使用者。 如果函式成功，它會接收代表登入使用者的權杖控制碼。 然後，您可以使用此權杖控制碼來模擬指定的使用者，或在大多數情況下，建立在指定使用者內容中執行 的進程 。
此函式類似于 LogonUserEx 函式，不同之處在于它會採用其他參數 pTokenGroups，這是一組一或多個 安全性識別碼 ， (SID) ，這些識別碼會在登入成功時新增至呼叫端傳回的權杖。
此函式不會在公用標頭中宣告，而且沒有相關聯的匯入程式庫。 您必須使用 LoadLibrary 和 GetProcAddress 函式動態連結至Advapi32.dll。
語法
BOOL WINAPI LogonUserExExW(
_In_ LPTSTR lpszUsername,
_In_opt_ LPTSTR lpszDomain,
_In_opt_ LPTSTR lpszPassword,
_In_ DWORD dwLogonType,
_In_ DWORD dwLogonProvider,
_In_opt_ PTOKEN_GROUPS pTokenGroups,
_Out_opt_ PHANDLE phToken,
_Out_opt_ PSID *ppLogonSid,
_Out_opt_ PVOID *ppProfileBuffer,
_Out_opt_ LPDWORD pdwProfileLength,
_Out_opt_ PQUOTA_LIMITS pQuotaLimits
);
參數
-
lpszUsername [in]
-
指定使用者名稱之 Null 終止字串的指標。 這是要登入的使用者帳戶名稱。 如果您使用 使用者主體名稱 (UPN) 格式， lpszDomain 參數必須是 Null。
-
lpszDomain [in， optional]
-
Null 終止字串的指標，指定帳戶資料庫包含 lpszUsername 帳戶之網域或伺服器的名稱。 如果此參數為 Null，則必須以 UPN 格式指定使用者名稱。 如果此參數為 「.」，則函式只會使用本機帳戶資料庫來驗證帳戶。
-
lpszPassword [in， optional]
-
Null 終止字串的指標，指定 lpszUsername所指定使用者帳戶的純文字密碼。 當您完成使用密碼時，請呼叫 SecureZeroMemory 函式 ，從記憶體清除密碼。 如需保護密碼的詳細資訊，請參閱 處理密碼。
-
dwLogonType [in]
-
要執行的登入作業類型。 此參數可以是下列其中一個值。
值 意義 - LOGON32_LOGON_INTERACTIVE
- 2
此登入類型適用于以互動方式使用電腦的使用者，例如 由終端 機伺服器、遠端殼層或類似程式登入的使用者。 此登入類型有快取已中斷連線作業之登入資訊的額外費用;因此，某些用戶端/伺服器應用程式不適當，例如郵件伺服器。 - LOGON32_LOGON_NETWORK
- 3
此登入類型適用于高效能伺服器來驗證純文字密碼。 LogonUserExW函式不會快取此登入類型的認證。 - LOGON32_LOGON_BATCH
- 4
此登入類型適用于批次伺服器，其中進程可能會代表使用者執行，而不需直接介入。 此類型也適用于一次處理許多純文字驗證嘗試的高效能伺服器，例如郵件或網頁伺服器。 LogonUserExW函式不會快取此登入類型的認證。 - LOGON32_LOGON_SERVICE
- 5
表示服務類型登入。 提供的帳戶必須啟用服務許可權。 - LOGON32_LOGON_UNLOCK
- 7
此登入類型適用于以互動方式使用電腦登入使用者的 GINA DLL。 此登入類型可以產生唯一的稽核記錄，顯示工作站解除鎖定時。 - LOGON32_LOGON_NETWORK_CLEARTEXT
- 8
此登入類型會保留 驗證套件中的名稱和密碼，這可讓伺服器在模擬用戶端時連線到其他網路伺服器。 伺服器可以接受來自用戶端的純文字認證、呼叫 LogonUserExExW、確認使用者可以跨網路存取系統，但仍與其他伺服器通訊。 - LOGON32_LOGON_NEW_CREDENTIALS
- 9
此登入類型可讓呼叫端複製其目前權杖，並指定輸出連線的新認證。 新的登入會話具有相同的本機識別碼，但會針對其他網路連線使用不同的認證。
只有 LOGON32_PROVIDER_WINNT50 登入提供者才支援此登入類型。 -
dwLogonProvider [in]
-
登入提供者。 此參數可以是下列其中一個值。
值 意義 - LOGON32_PROVIDER_DEFAULT
使用系統的標準登入提供者。 預設 安全性提供者 為 NTLM。 - LOGON32_PROVIDER_WINNT50
使用交涉登入提供者。 - LOGON32_PROVIDER_WINNT40
使用 NTLM 登入提供者。 -
pTokenGroups [in， optional]
-
TOKEN_GROUPS結構的指標，指定加入此函式成功登入時所接收之權杖的群組 SID 清單。 新增至權杖的任何 SID 也會影響群組擴充。 例如，如果新增的 SID 是本機群組的成員，這些群組也會新增至收到的存取權杖。
如果此參數不是 Null，則此函式的呼叫端必須具有授與並啟用 SE_TCB_PRIVILEGE 許可權。
-
phToken [out， 選擇性]
-
控制碼變數的指標，可接收代表指定之使用者的權杖控制碼。
您可以在對 ImpersonateLoggedOnUser 函式的呼叫中使用傳回的控制碼。
在大部分情況下，傳回的控制碼是可在呼叫 CreateProcessAsUser函式時使用的主要權杖。 不過，如果您指定LOGON32_LOGON_NETWORK旗標，LogonUserExW會傳回無法在CreateProcessAsUser中使用的模擬權杖，除非您呼叫DuplicateTokenEx將模擬權杖轉換為主要權杖。
當您不再需要此控制碼時，請呼叫 CloseHandle 函式 加以關閉。
-
ppLogonSid [out， 選擇性]
-
接收使用者登入之 SID 之 SID 之指標的指標。
當您完成使用 SID 時，請呼叫 LocalFree 函式來釋出它。
-
ppProfileBuffer [out， optional]
-
指標，可接收包含登入使用者設定檔之緩衝區位址的指標。
-
pdwProfileLength [out， optional]
-
接收配置檔案緩衝區長度的 DWORD 指標。
-
pQuotaLimits [out， optional]
-
QUOTA_LIMITS結構的指標，可接收已登入使用者配額的相關資訊。
傳回值
如果函式成功，函式會傳回非零。
如果函式失敗，它會傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
備註
LOGON32_LOGON_NETWORK登入類型最快，但有下列限制：
- 函式會傳回 模擬權杖，而不是主要權杖。 您無法直接在 CreateProcessAsUser 函式中使用此權杖。 不過，您可以呼叫 DuplicateTokenEx 函式，將權杖轉換成主要權杖，然後在 CreateProcessAsUser中使用它。
- 如果您將權杖轉換成主要權杖，並在 CreateProcessAsUser 中使用它來啟動進程，則新進程無法透過重新導向器存取其他網路資源，例如遠端伺服器或印表機。 例外狀況是，如果網路資源不受存取控制，則新進程將能夠存取它。
由 lpszUsername指定的帳號必須具有必要的帳戶許可權。 例如，若要以 LOGON32_LOGON_INTERACTIVE 旗標登入使用者，使用者 (或使用者所屬的群組) 必須擁有 SE_INTERACTIVE_LOGON_NAME 帳戶許可權。 如需影響各種登入作業的帳戶許可權清單，請參閱 帳戶物件存取權限。
如果至少有一個權杖存在，則會將使用者視為登入。 如果您呼叫 CreateProcessAsUser ，然後關閉權杖，使用者仍會登入，直到進程 (和所有子進程) 結束為止。
如果提供選擇性 的 pTokenGroups 參數，LSA 將不會自動新增本機 SID 或登入 SID。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows Server 2008 [僅限傳統型應用程式] |
| 版本 |
LogonUserExExW 也可在 Windows Server 2003 或 Windows XP 上使用一般散發版本。 |
| 標頭 |
|
| DLL |
|
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應