LogonUserExExW-Funktion
Die LogonUserExExW-Funktion versucht, einen Benutzer auf dem lokalen Computer zu protokollieren. Der lokale Computer ist der Computer, von dem LogonUserExW aufgerufen wurde. Sie können logonUserExExW nicht verwenden, um sich bei einem Remotecomputer anzumelden. Geben Sie den Benutzer mithilfe eines Benutzernamens und einer Domäne an, und authentifizieren Sie den Benutzer mithilfe eines Klartextkennworts. Wenn die Funktion erfolgreich ist, empfängt sie ein Handle für ein Token, das den angemeldeten Benutzer darstellt. Sie können dann dieses Tokenhandle verwenden, um die Identität des angegebenen Benutzers zu übernehmen oder in den meisten Fällen einen Prozess zu erstellen, der im Kontext des angegebenen Benutzers ausgeführt wird.
Diese Funktion ähnelt der LogonUserEx-Funktion , mit der Ausnahme, dass sie den zusätzlichen Parameter pTokenGroups verwendet, bei dem es sich um einen Satz von mindestens einem Sicherheitsbezeichner (SIDs) handelt, die dem Token hinzugefügt werden, das dem Aufrufer zurückgegeben wird, wenn die Anmeldung erfolgreich ist.
Diese Funktion wird nicht in einem öffentlichen Header deklariert und verfügt über keine zugehörige Importbibliothek. Sie müssen die Funktionen LoadLibrary und GetProcAddress verwenden, um eine dynamische Verknüpfung mit Advapi32.dll.
Syntax
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
);
Parameter
-
lpszUsername [in]
-
Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Benutzers angibt. Dies ist der Name des Benutzerkontos, bei dem sie sich anmelden möchten. Wenn Sie das UPN-Format ( User Principal Name ) verwenden, muss der lpszDomain-ParameterNULL sein.
-
lpszDomain [in, optional]
-
Ein Zeiger auf eine null-beendete Zeichenfolge, die den Namen der Domäne oder des Servers angibt, deren Kontodatenbank das LpszUsername-Konto enthält. Wenn dieser Parameter NULL ist, muss der Benutzername im UPN-Format angegeben werden. Wenn dieser Parameter "." ist, überprüft die Funktion das Konto nur mithilfe der lokalen Kontodatenbank.
-
lpszPassword [in, optional]
-
Ein Zeiger auf eine null-beendete Zeichenfolge, die das Klartextkennwort für das von lpszUsername angegebene Benutzerkonto angibt. Wenn Sie das Kennwort verwendet haben, löschen Sie das Kennwort aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen. Weitere Informationen zum Schutz von Kennwörtern finden Sie unter Behandeln von Kennwörtern.
-
dwLogonType [in]
-
Der Typ des auszuführenden Anmeldevorgangs. Dieser Parameter kann einen der folgenden Werte annehmen.
Wert Bedeutung - LOGON32_LOGON_INTERACTIVE
- 2
Dieser Anmeldetyp ist für Benutzer vorgesehen, die den Computer interaktiv verwenden, z. B. einen Benutzer, der über einen Terminalserver , eine Remoteshell oder einen ähnlichen Prozess angemeldet ist. Dieser Anmeldetyp hat zusätzliche Kosten für das Zwischenspeichern von Anmeldeinformationen für getrennte Vorgänge. Daher ist dies für einige Client-/Serveranwendungen, z. B. für einen Mailserver, ungeeignet. - LOGON32_LOGON_NETWORK
- 3
Dieser Anmeldetyp ist für Hochleistungsserver vorgesehen, um Klartextkennwörter zu authentifizieren. Die LogonUserExExW-Funktion speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen. - LOGON32_LOGON_BATCH
- 4
Dieser Anmeldetyp ist für Batchserver vorgesehen, bei denen Prozesse möglicherweise im Namen eines Benutzers ohne ihren direkten Eingriff ausgeführt werden. Dieser Typ ist auch für Server mit höherer Leistung geeignet, die viele Klartextauthentifizierungsversuche gleichzeitig verarbeiten, z. B. E-Mails oder Webserver. Die LogonUserExExW-Funktion speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen. - LOGON32_LOGON_SERVICE
- 5
Gibt eine Diensttypanmeldung an. Für das bereitgestellte Konto muss die Dienstberechtigung aktiviert sein. - LOGON32_LOGON_UNLOCK
- 7
Dieser Anmeldetyp ist für GINA-DLLs vorgesehen, die Benutzer anmelden, die interaktiv den Computer verwenden. Dieser Anmeldetyp kann einen eindeutigen Überwachungsdatensatz generieren, der anzeigt, wann die Arbeitsstation entsperrt wurde. - LOGON32_LOGON_NETWORK_CLEARTEXT
- 8
Dieser Anmeldetyp behält den Namen und das Kennwort im Authentifizierungspaket bei, sodass der Server Verbindungen mit anderen Netzwerkservern herstellen kann, während er die Identität des Clients angibt. Ein Server kann Klartextanmeldeinformationen von einem Client akzeptieren, LogonUserExExW aufrufen, überprüfen, ob der Benutzer über das Netzwerk auf das System zugreifen kann, und weiterhin mit anderen Servern kommunizieren. - LOGON32_LOGON_NEW_CREDENTIALS
- 9
Mit diesem Anmeldetyp kann der Aufrufer sein aktuelles Token klonen und neue Anmeldeinformationen für ausgehende Verbindungen angeben. Die neue Anmeldesitzung weist den gleichen lokalen Bezeichner auf, verwendet jedoch unterschiedliche Anmeldeinformationen für andere Netzwerkverbindungen.
Dieser Anmeldetyp wird nur vom LOGON32_PROVIDER_WINNT50 Anmeldeanbieter unterstützt. -
dwLogonProvider [in]
-
Der Anmeldeanbieter. Dieser Parameter kann einen der folgenden Werte annehmen.
Wert Bedeutung - LOGON32_PROVIDER_DEFAULT
Verwenden Sie den Standardanmeldungsanbieter für das System. Der Standardsicherheitsanbieter ist NTLM. - LOGON32_PROVIDER_WINNT50
Verwenden Sie den Anbieter für die Aushandlungsanmeldung. - LOGON32_PROVIDER_WINNT40
Verwenden Sie den NTLM-Anmeldeanbieter. -
pTokenGroups [in, optional]
-
Ein Zeiger auf eine TOKEN_GROUPS-Struktur , die eine Liste von Gruppen-SIDs angibt, die dem Token hinzugefügt werden, das diese Funktion bei erfolgreicher Anmeldung empfängt. Alle SIDs, die dem Token hinzugefügt werden, wirken sich auch auf die Gruppenerweiterung aus. Wenn die hinzugefügten SIDs beispielsweise Mitglieder lokaler Gruppen sind, werden diese Gruppen auch dem empfangenen Zugriffstoken hinzugefügt.
Wenn dieser Parameter nicht NULL ist, muss dem Aufrufer dieser Funktion die SE_TCB_PRIVILEGE Berechtigung erteilt und aktiviert sein.
-
phToken [out, optional]
-
Ein Zeiger auf eine Handle-Variable, die ein Handle auf ein Token empfängt, das den angegebenen Benutzer darstellt.
Sie können das zurückgegebene Handle in Aufrufen der Funktion ImpersonateLoggedOnUser verwenden.
In den meisten Fällen ist das zurückgegebene Handle ein primäres Token , das Sie in Aufrufen der CreateProcessAsUser-Funktion verwenden können. Wenn Sie jedoch das flag LOGON32_LOGON_NETWORK angeben, gibt LogonUserExExW ein Identitätswechseltoken zurück, das Sie in CreateProcessAsUser nicht verwenden können, es sei denn , Sie rufen DuplicateTokenEx auf, um das Identitätswechseltoken in ein primäres Token zu konvertieren.
Wenn Sie dieses Handle nicht mehr benötigen, schließen Sie es, indem Sie die CloseHandle-Funktion aufrufen.
-
ppLogonSid [out, optional]
-
Ein Zeiger auf einen Zeiger auf eine SID, die die SID des angemeldeten Benutzers empfängt.
Wenn Sie die SID verwendet haben, geben Sie sie frei, indem Sie die LocalFree-Funktion aufrufen.
-
ppProfileBuffer [out, optional]
-
Ein Zeiger auf einen Zeiger, der die Adresse eines Puffers empfängt, der das Profil des angemeldeten Benutzers enthält.
-
pdwProfileLength [out, optional]
-
Ein Zeiger auf ein DWORD , das die Länge des Profilpuffers empfängt.
-
pQuotaLimits [out, optional]
-
Ein Zeiger auf eine QUOTA_LIMITS-Struktur , die Informationen zu den Kontingenten für den angemeldeten Benutzer empfängt.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero zurück.
Wenn die Funktion fehlschlägt, gibt sie null zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Bemerkungen
Der LOGON32_LOGON_NETWORK Anmeldetyp ist am schnellsten, weist jedoch die folgenden Einschränkungen auf:
- Die Funktion gibt ein Identitätswechseltoken und kein primäres Token zurück. Sie können dieses Token nicht direkt in der Funktion CreateProcessAsUser verwenden. Sie können jedoch die DuplicateTokenEx-Funktion aufrufen, um das Token in ein primäres Token zu konvertieren, und sie dann in CreateProcessAsUser verwenden.
- Wenn Sie das Token in ein primäres Token konvertieren und es in CreateProcessAsUser verwenden, um einen Prozess zu starten, kann der neue Prozess nicht über den Redirector auf andere Netzwerkressourcen wie Remoteserver oder Drucker zugreifen. Eine Ausnahme besteht darin, dass der neue Prozess auf die Netzwerkressource zugreifen kann, wenn der Zugriff nicht gesteuert wird.
Das von lpszUsername angegebene Konto muss über die erforderlichen Kontorechte verfügen. Um sich beispielsweise bei einem Benutzer mit dem LOGON32_LOGON_INTERACTIVE-Flag anzumelden, muss der Benutzer (oder eine Gruppe, zu der der Benutzer gehört) über das SE_INTERACTIVE_LOGON_NAME-Kontorecht verfügen. Eine Liste der Kontorechte, die sich auf die verschiedenen Anmeldevorgänge auswirken, finden Sie unter Kontoobjektzugriffsrechte.
Ein Benutzer gilt als angemeldet, wenn mindestens ein Token vorhanden ist. Wenn Sie CreateProcessAsUser aufrufen und dann das Token schließen, ist der Benutzer weiterhin angemeldet, bis der Prozess (und alle untergeordneten Prozesse) beendet sind.
Wenn der optionale pTokenGroups-Parameter angegeben wird, fügt LSA weder die lokale SID noch die Anmelde-SID automatisch hinzu.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) |
Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) |
Windows Server 2008 [nur Desktop-Apps] |
| Version |
LogonUserExExW ist auch unterWindows Server 2003 oder Windows XP mit dem Allgemeinen Verteilungsrelease verfügbar. |
| Header |
|
| DLL |
|
Siehe auch