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	Winbasep.h
DLL	Advapi32.dll

Siehe auch

Client/Server-Access Control

Client-/Server-Access Control-Funktionen

Closehandle

CreateProcessAsUser

DuplicateTokenEx

IdentitätswechselLoggedOnUser

LogonUserEx

QUOTA_LIMITS