LogonUserExW-Funktion (winbase.h)

Artikel
11/20/2024

Die LogonUserEx--Funktion versucht, einen Benutzer auf dem lokalen Computer anzumelden. Der lokale Computer ist der Computer, von dem LogonUserEx aufgerufen wurde. Sie können LogonUserEx- nicht verwenden, um sich bei einem Remotecomputer anzumelden. Sie geben den Benutzer mit einem Benutzernamen und einer Domäne an und sich Benutzer mit einem Nur-Text-Kennwort authentifizieren. Wenn die Funktion erfolgreich ist, erhalten Sie ein Handle zu einem Token, das den angemeldeten Benutzer darstellt. Anschließend können Sie 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.

Syntax

BOOL LogonUserExW(
  [in]            LPCWSTR       lpszUsername,
  [in, optional]  LPCWSTR       lpszDomain,
  [in, optional]  LPCWSTR       lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

Parameter

[in] lpszUsername

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Namen des Benutzers angibt. Dies ist der Name des Benutzerkontos, bei dem sich anmelden soll. Wenn Sie das Benutzerprinzipalnamen-Format (UPN) user@DNS_domain_name verwenden, muss der parameter lpszDomainNULL-sein.

[in, optional] lpszDomain

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Namen der Domäne oder des Servers angibt, deren Kontodatenbank den lpszUsername Konto enthält. Wenn dieser Parameter NULL-ist, muss der Benutzername im UPN-Format angegeben werden. Wenn dieser Parameter "." lautet, überprüft die Funktion das Konto nur mithilfe der lokalen Kontodatenbank.

[in, optional] lpszPassword

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die das Nur-Text-Kennwort für das Benutzerkonto angibt, das durch lpszUsernameangegeben wird. Wenn Sie mit der Verwendung des Kennworts fertig sind, löschen Sie das Kennwort aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen. Weitere Informationen zum Schützen von Kennwörtern finden Sie unter Behandeln von Kennwörtern.

[in] dwLogonType

Der Typ des auszuführenden Anmeldevorgangs. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
LOGON32_LOGON_BATCH	Dieser Anmeldetyp ist für Batchserver vorgesehen, bei denen Prozesse im Auftrag eines Benutzers ohne direkte Intervention ausgeführt werden können. Dieser Typ ist auch für Server mit höherer Leistung vorgesehen, die viele Nur-Text-Authentifizierungsversuche gleichzeitig verarbeiten, z. B. E-Mail- oder Webserver. Die funktion LogonUserEx speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen.
LOGON32_LOGON_INTERACTIVE	Dieser Anmeldetyp ist für Benutzer vorgesehen, die interaktiv den Computer verwenden, z. B. einen Benutzer, der von einem Terminal Server, Remoteshell oder einem ähnlichen Prozess angemeldet ist. Dieser Anmeldetyp hat die zusätzlichen Kosten für die Zwischenspeicherung von Anmeldeinformationen für getrennte Vorgänge; Daher ist es für einige Client-/Serveranwendungen, wie z. B. einen E-Mail-Server, unangemessen.
LOGON32_LOGON_NETWORK	Dieser Anmeldetyp ist für Hochleistungsserver zum Authentifizieren von Nur-Text-Kennwörtern vorgesehen. Die funktion LogonUserEx speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen.
LOGON32_LOGON_NETWORK_CLEARTEXT	Dieser Anmeldetyp behält den Namen und das Kennwort im Authentifizierungspaketbei, mit dem der Server Verbindungen zu anderen Netzwerkservern herstellen kann, während der Identitätswechsel des Clients erfolgt. Ein Server kann Nur-Text-Anmeldeinformationen von einem Client akzeptieren, LogonUserEx-aufrufen, überprüfen, ob der Benutzer über das Netzwerk auf das System zugreifen kann und trotzdem mit anderen Servern kommunizieren kann.
LOGON32_LOGON_NEW_CREDENTIALS	Dieser Anmeldetyp ermöglicht es dem Aufrufer, sein aktuelles Token zu klonen und neue Anmeldeinformationen für ausgehende Verbindungen anzugeben. Die neue Anmeldesitzung weist denselben lokalen Bezeichner auf, verwendet jedoch unterschiedliche Anmeldeinformationen für andere Netzwerkverbindungen. Dieser Anmeldetyp wird nur vom LOGON32_PROVIDER_WINNT50 Anmeldeanbieter unterstützt.
LOGON32_LOGON_SERVICE	Gibt eine Diensttypanmeldung an. Das bereitgestellte Konto muss die Dienstberechtigung aktiviert haben.
LOGON32_LOGON_UNLOCK	Dieser Anmeldetyp richtet sich an GINA DLLs, die sich bei Benutzern anmelden, die interaktiv mit dem Computer verwendet werden. Dieser Anmeldetyp kann einen eindeutigen Überwachungsdatensatz generieren, der anzeigt, wann die Arbeitsstation entsperrt wurde.

[in] dwLogonProvider

Der Anmeldeanbieter. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
LOGON32_PROVIDER_DEFAULT	Verwenden Sie den Standardanmeldungsanbieter für das System. Der standardmäßige Sicherheitsanbieter ist NTLM.
LOGON32_PROVIDER_WINNT50	Verwenden Sie den Aushandlungsanmeldungsanbieter.
LOGON32_PROVIDER_WINNT40	Verwenden Sie den NTLM-Anmeldeanbieter.

[out, optional] phToken

Ein Zeiger auf eine Handlevariable, die ein Handle zu einem Token empfängt, das den angegebenen Benutzer darstellt.

Sie können das zurückgegebene Handle in Aufrufen der ImpersonateLoggedOnUser--Funktion verwenden.

In den meisten Fällen ist das zurückgegebene Handle ein primären Token, das Sie in Aufrufen der CreateProcessAsUser--Funktion verwenden können. Wenn Sie jedoch das LOGON32_LOGON_NETWORK-Flag angeben, gibt LogonUserEx ein Identitätswechsel token zurück, das Sie nicht in CreateProcessAsUser- 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.

[out, optional] ppLogonSid

Ein Zeiger auf einen Zeiger auf einen Sicherheitsbezeichner (SID), der die SID des angemeldeten Benutzers empfängt.

Wenn Sie die SID verwendet haben, geben Sie sie frei, indem Sie die funktion LocalFree aufrufen.

[out, optional] ppProfileBuffer

Ein Zeiger auf einen Zeiger, der die Adresse eines Puffers empfängt, der das Profil des angemeldeten Benutzers enthält.

[out, optional] pdwProfileLength

Ein Zeiger auf eine DWORD-, die die Länge des Profilpuffers empfängt.

[out, optional] pQuotaLimits

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, wird null zurückgegeben. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Der anmeldetyp LOGON32_LOGON_NETWORK ist am schnellsten, hat jedoch die folgenden Einschränkungen:

Die Funktion gibt ein Identitätswechseltokenzurück, kein primäres Token. Sie können dieses Token nicht direkt in der CreateProcessAsUser--Funktion 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 auf andere Netzwerkressourcen wie Remoteserver oder Drucker über den Umleitungsmodul zugreifen. Eine Ausnahme besteht darin, dass der neue Prozess darauf zugreifen kann, wenn die Netzwerkressource nicht auf sie zugreifen kann.

Die SE_TCB_NAME Berechtigung ist für diese Funktion nicht erforderlich, es sei denn, Sie melden sich bei einem Passport-Konto an.

Das durch lpszUsername angegebene Konto muss über die erforderlichen Kontorechte verfügen. Um sich beispielsweise mit dem LOGON32_LOGON_INTERACTIVE-Flag bei einem Benutzer 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 Account Object Access Rights.

Ein Benutzer gilt als angemeldet, wenn mindestens ein Token vorhanden ist. Wenn Sie CreateProcessAsUser- aufrufen und dann das Token schließen, wird der Benutzer noch angemeldet, bis der Prozess (und alle untergeordneten Prozesse) beendet wurde.

Wenn der LogonUserEx Aufruf erfolgreich ist, benachrichtigt das System Netzwerkanbieter, dass die Anmeldung durch Aufrufen der NPLogonNotify Einstiegspunktfunktion aufgetreten ist.

Anmerkung

Der winbase.h-Header definiert LogonUserEx als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Advapi32.lib
DLL-	Advapi32.dll