LogonUserW-Funktion (winbase.h)

Artikel
11/20/2024

Die LogonUser--Funktion versucht, einen Benutzer auf dem lokalen Computer anzumelden. Der lokale Computer ist der Computer, von dem LogonUser aufgerufen wurde. Sie können LogonUser- 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 LogonUserW(
  [in]           LPCWSTR lpszUsername,
  [in, optional] LPCWSTR lpszDomain,
  [in, optional] LPCWSTR lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

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 (UPN)-Format verwenden, muss User@DNSDomainName, der parameter lpszDomainNULLsein.

[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 eine der folgenden Werte sein, die in Winbase.h definiert sind.

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.
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 LogonUser--Funktion 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, LogonUser-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. Hinweis: Ab Januar 2023 ist es nicht möglich, den LOGON32_LOGON_NEW_CREDENTIALS Anmeldetyp mit einem gruppenverwalteten Dienstkonto (Group Managed Service Account, gMSA) zu verwenden.
LOGON32_LOGON_SERVICE	Gibt eine Diensttypanmeldung an. Das bereitgestellte Konto muss die Dienstberechtigung aktiviert haben.
LOGON32_LOGON_UNLOCK	GINAs werden nicht mehr unterstützt. Windows Server 2003 und Windows XP: Dieser Anmeldetyp ist für GINA DLLs vorgesehen, die benutzerinteraktiv mit dem Computer anmelden. Dieser Anmeldetyp kann einen eindeutigen Überwachungsdatensatz generieren, der anzeigt, wann die Arbeitsstation entsperrt wurde.

[in] dwLogonProvider

Gibt den Anmeldeanbieter an. 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 aushandelt, es sei denn, Sie übergeben NULL- für den Domänennamen, und der Benutzername ist nicht im UPN-Format. In diesem Fall ist der Standardanbieter NTLM.
LOGON32_PROVIDER_WINNT50	Verwenden Sie den Aushandlungsanmeldungsanbieter.
LOGON32_PROVIDER_WINNT40	Verwenden Sie den NTLM-Anmeldeanbieter.

[out] 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 flag LOGON32_LOGON_NETWORK angeben, gibt LogonUser ein Identitätswechseltoken zurück, das Sie nicht in CreateProcessAsUser- verwenden können, es sei denn, Sie rufen DuplicateTokenEx auf, um es 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.

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 lpszUsernameangegebene 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 Kontorechtekonstanten.

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

Wenn der aufruf LogonUser erfolgreich ist, benachrichtigt das System Netzwerkanbieter, dass die Anmeldung durch Aufrufen der NPLogonNotify Einstiegspunktfunktion des Anbieters aufgetreten ist.

Beispiele

Sie können ein LocalService-Token mithilfe des folgenden Codes generieren.

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

Anmerkung

Der winbase.h-Header definiert LogonUser als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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