LogonUserA-Funktion (winbase.h)

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.

[in] dwLogonProvider

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

[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)

Anforderungen

Weitere Informationen

Client/Server-Access Control

Client-/Server-Access Control-Funktionen

CloseHandle

CreateProcessAsUser

DuplicateTokenEx

ImpersonateLoggedOnUser