LogonUserExA-Funktion (winbase.h)
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 |
|---|---|
|
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. |
|
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. |
|
Dieser Anmeldetyp ist für Hochleistungsserver vorgesehen, um Klartextkennwörter zu authentifizieren. Die LogonUserEx-Funktion speichert keine Anmeldeinformationen für diesen Anmeldetyp zwischen. |
|
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. |
|
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. |
|
Gibt eine Diensttypanmeldung an. Für das bereitgestellte Konto muss die Dienstberechtigung aktiviert sein. |
|
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 |
|---|---|
|
Verwenden Sie den Standard-Anmeldeanbieter für das System. Der Standardsicherheitsanbieter ist NTLM. |
|
Verwenden Sie den Negotiate-Anmeldeanbieter. |
|
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 |