LogonUserExA-Funktion (winbase.h)

Artikel
08/27/2023

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 authentifizieren den Benutzer mit einem Klartextkennwort. Wenn die Funktion erfolgreich ist, erhalten Sie ein Handle für ein Token, das den angemeldeten Benutzer darstellt. Mit diesem Tokenhandle können Sie dann die Identität des angegebenen Benutzers annehmen oder in den meisten Fällen einen Prozess erstellen, der im Kontext des angegebenen Benutzers ausgeführt wird.

Syntax

BOOL LogonUserExA(
  [in]            LPCSTR        lpszUsername,
  [in, optional]  LPCSTR        lpszDomain,
  [in, optional]  LPCSTR        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 NULL-endende 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, Benutzerprinzipalname ) user@DNS_domain_name verwenden, muss der lpszDomain-ParameterNULL sein.

[in, optional] lpszDomain

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Namen der Domäne oder des Servers angibt, deren Kontodatenbank das Konto lpszUsername 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 null-endende Zeichenfolge, die das Klartextkennwort für das von lpszUsername angegebene Benutzerkonto angibt. Wenn Sie die Verwendung des Kennworts abgeschlossen haben, 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 einen der folgenden Werte annehmen.

Wert	Bedeutung
LOGON32_LOGON_BATCH	Dieser Anmeldetyp ist für Batchserver vorgesehen, bei denen Prozesse im Namen eines Benutzers ohne direkten Eingriff ausgeführt werden können. Dieser Typ ist auch für Server mit höherer Leistung geeignet, die viele Klartextauthentifizierungsversuche gleichzeitig verarbeiten, z. B. E-Mail- oder Webserver. Die LogonUserEx-Funktion speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen.
LOGON32_LOGON_INTERACTIVE	Dieser Anmeldetyp ist für Benutzer gedacht, die den Computer interaktiv verwenden, z. B. einen Benutzer, der über einen Terminalserver , eine Remoteshell oder einen ähnlichen Prozess angemeldet ist. Dieser Anmeldetyp hat den zusätzlichen Aufwand für das Zwischenspeichern von Anmeldeinformationen für getrennte Vorgänge. Daher ist es für einige Client-/Serveranwendungen, z. B. einen Mailserver, ungeeignet.
LOGON32_LOGON_NETWORK	Dieser Anmeldetyp ist für Hochleistungsserver vorgesehen, um Klartextkennwörter zu authentifizieren. Die LogonUserEx-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, wodurch der Server Verbindungen mit anderen Netzwerkservern herstellen kann, während er die Identität des Clients angibt. 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 weiterhin 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 andere Anmeldeinformationen für andere Netzwerkverbindungen. Dieser Anmeldetyp wird nur vom LOGON32_PROVIDER_WINNT50-Anmeldeanbieter unterstützt.
LOGON32_LOGON_SERVICE	Gibt eine Diensttypanmeldung an. Für das bereitgestellte Konto muss die Dienstberechtigung aktiviert sein.
LOGON32_LOGON_UNLOCK	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

Der Anmeldeanbieter. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
LOGON32_PROVIDER_DEFAULT	Verwenden Sie den Standard-Anmeldeanbieter für das System. Der Standardsicherheitsanbieter ist NTLM.
LOGON32_PROVIDER_WINNT50	Verwenden Sie den Negotiate-Anmeldeanbieter.
LOGON32_PROVIDER_WINNT40	Verwenden Sie den NTLM-Anmeldeanbieter.

[out, optional] phToken

Ein Zeiger auf eine Handle-Variable, die ein Handle für 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 LogonUserEx ein Identitätswechseltoken zurück, das Sie in CreateProcessAsUser nur verwenden können, wenn Sie DuplicateTokenEx aufrufen, 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 eine Sicherheits-ID (SID), die die SID des angemeldeten Benutzers empfängt.

Wenn Sie die Verwendung der SID abgeschlossen 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 ein DWORD , das 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 ungleich null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. 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 CreateProcessAsUser-Funktion verwenden. Sie können jedoch die DuplicateTokenEx-Funktion aufrufen, um das Token in ein primäres Token zu konvertieren, und es 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 Umleitungsor auf andere Netzwerkressourcen wie Remoteserver oder Drucker zugreifen. Eine Ausnahme besteht darin, dass der neue Prozess darauf zugreifen kann, wenn die Netzwerkressource nicht über den Zugriff 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 von lpszUsername angegebene Konto muss über die erforderlichen Kontorechte verfügen. Wenn Sie sich beispielsweise mit dem flag LOGON32_LOGON_INTERACTIVE bei einem Benutzer anmelden möchten, 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 Zugriffsberechtigungen für Kontoobjekte.

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 LogonUserEx-Aufruf erfolgreich ist, benachrichtigt das System netzwerkanbieter, dass die Anmeldung erfolgt ist, indem die NpLogonNotify-Einstiegspunktfunktion des Anbieters aufgerufen wird.

Hinweis

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