LogonUserW-Funktion (winbase.h)
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 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 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 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) (UserPrincipal Name, User @DNSDomainName) 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 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 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 einer der folgenden Werte sein, die in Winbase.h definiert sind.
| Wert | Bedeutung |
|---|---|
|
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. |
|
Dieser Anmeldetyp richtet sich an Benutzer, 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. |
|
Dieser Anmeldetyp ist für Hochleistungsserver vorgesehen, um Klartextkennwörter zu authentifizieren. Die LogonUser-Funktion speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen. |
|
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 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. |
|
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. 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. |
|
Gibt eine Diensttypanmeldung an. Für das bereitgestellte Konto muss die Dienstberechtigung aktiviert sein. |
|
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 |
|---|---|
|
Verwenden Sie den Standard-Anmeldeanbieter für das System. Der Standardsicherheitsanbieter ist aushandeln, es sei denn, Sie übergeben NULL für den Domänennamen und der Benutzername hat nicht das UPN-Format. In diesem Fall ist der Standardanbieter NTLM. |
|
Verwenden Sie den Negotiate-Anmeldeanbieter. |
|
Verwenden Sie den NTLM-Anmeldeanbieter. |
[out] 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 LogonUser ein Identitätswechseltoken zurück, das Sie in CreateProcessAsUser nur verwenden können, wenn Sie DuplicateTokenEx aufrufen, 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 ungleich null zurück.
Wenn die Funktion fehlschlägt, wird null zurückgegeben. 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 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 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 generieren, indem Sie den folgenden Code verwenden.
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 Aliases 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
| 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 |