LogonUserA-Funktion (winbase.h)

Artikel
06/01/2023

Die LogonUser-Funktion versucht, einen Benutzer auf dem lokalen Computer zu protokollieren. 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 authentifizieren den Benutzer mit einem Klartextkennwort . Wenn die Funktion erfolgreich ist, erhalten 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.

Syntax

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

Parameter

[in] lpszUsername

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, User@DNSDomainName, muss der lpszDomain-ParameterNULL sein.

[in, optional] lpszDomain

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.

[in, optional] lpszPassword

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.

[in] dwLogonType

Der Typ des auszuführenden Anmeldevorgangs. Dieser Parameter kann einer 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 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.
LOGON32_LOGON_INTERACTIVE	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	Dieser Anmeldetyp ist für Hochleistungsserver vorgesehen, um Klartextkennwörter zu authentifizieren. 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 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, LogonUser aufrufen, überprüfen, ob der Benutzer über das Netzwerk auf das System zugreifen kann, und weiterhin mit anderen Servern kommunizieren.
LOGON32_LOGON_NEW_CREDENTIALS	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. Hinweis: Ab Januar 2023 ist es nicht möglich, den Anmeldetyp LOGON32_LOGON_NEW_CREDENTIALS mit einem gruppenverwalteten Dienstkonto (Group Managed Service Account, gMSA) zu verwenden.
LOGON32_LOGON_SERVICE	Gibt eine Diensttypanmeldung an. Für das bereitgestellte Konto muss die Dienstberechtigung aktiviert sein.
LOGON32_LOGON_UNLOCK	GINAs werden nicht mehr unterstützt. Windows Server 2003 und Windows XP: 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.

[in] dwLogonProvider

Gibt den Anmeldeanbieter an. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
LOGON32_PROVIDER_DEFAULT	Verwenden Sie den Standardanmeldungsanbieter für das System. Der Standardsicherheitsanbieter wird ausgehandelt, es sei denn, Sie übergeben NULL für den Domänennamen und der Benutzername hat kein UPN-Format. In diesem Fall ist der Standardanbieter NTLM.
LOGON32_PROVIDER_WINNT50	Verwenden Sie den Anbieter für die Aushandlungsanmeldung.
LOGON32_PROVIDER_WINNT40	Verwenden Sie den NTLM-Anmeldeanbieter.

[out] phToken

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 LogonUser ein Identitätswechseltoken zurück, das Sie in CreateProcessAsUser nicht 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, gibt sie null zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

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.

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 bei einem Benutzer mit dem Flag LOGON32_LOGON_INTERACTIVE 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 weiterhin angemeldet, bis der Prozess (und alle untergeordneten Prozesse) beendet sind.

Wenn der LogonUser-Aufruf erfolgreich ist, benachrichtigt das System netzwerkanbieter, dass die Anmeldung erfolgt ist, indem die NPLogonNotify-Einstiegspunktfunktion des Anbieters aufgerufen wird.

Beispiele

Sie können ein LocalService-Token mit dem folgenden Code generieren.

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

Hinweis

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 nicht codierungsneutralem Code 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
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll