LSA_AP_LOGON_USER_EX Rückruffunktion (ntsecpkg.h)

Artikel
08/25/2023

Authentifiziert die Anmeldeinformationen eines Benutzers.

Diese Funktion wird von der lokalen Sicherheitsbehörde (LSA ) nur für die anfängliche Anmeldung eines Benutzers aufgerufen. Nachfolgende Authentifizierungsanforderungen müssen LsaCallAuthenticationPackage verwenden. Wenn LsaApLogonUserEx erfolgreich ist, erstellt es eine Anmeldesitzung und gibt Informationen zurück, die zum Erstellen des Tokens verwendet werden, das den neu angemeldeten Benutzer darstellt.

Diese Funktion unterscheidet sich von LsaApLogonUser darin, dass der Computername dem Überwachungsdatensatz für den Anmeldeversuch hinzugefügt wird.

Syntax

LSA_AP_LOGON_USER_EX LsaApLogonUserEx;

NTSTATUS LsaApLogonUserEx(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID AuthenticationInformation,
  [in]  PVOID ClientAuthenticationBase,
  [in]  ULONG AuthenticationInformationLength,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferLength,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PUNICODE_STRING *AccountName,
  [out] PUNICODE_STRING *AuthenticatingAuthority,
  [out] PUNICODE_STRING *MachineName
)
{...}

Parameter

[in] ClientRequest

Zeiger auf einen nicht transparenten LSA_CLIENT_REQUEST Datentyp, der die Anforderung des LSA-Clients darstellt.

[in] LogonType

Eine SECURITY_LOGON_TYPE Struktur, die den Typ der versuchten Anmeldung identifiziert.

[in] AuthenticationInformation

Stellt die Authentifizierungsinformationen für das Authentifizierungspaket bereit. Der LSA gibt diesen Puffer frei.

[in] ClientAuthenticationBase

Stellt die Adresse der Authentifizierungsinformationen innerhalb des Clientprozesses bereit. Dies kann erforderlich sein, um Zeiger innerhalb des AuthenticationInformation-Puffers neu zuzuordnen.

[in] AuthenticationInformationLength

Gibt die Länge des AuthenticationInformation-Puffers an.

[out] ProfileBuffer

Zeiger, der die Adresse des Profilpuffers im Clientprozess empfängt. Das Authentifizierungspaket ist für die Zuweisung des ProfileBuffer-Puffers innerhalb des Clientprozesses durch Aufrufen der AllocateClientBuffer-Funktion verantwortlich. Wenn bei der LSA jedoch anschließend ein Fehler auftritt, der eine erfolgreiche Anmeldung verhindert, kümmert sich die LSA um die Freigabe dieses Puffers.

Der Inhalt dieses Puffers wird durch das Authentifizierungspaket bestimmt. Der LSA ändert diesen Puffer nicht. Es gibt einfach den Wert an die LsaLogonUser-Funktion zurück.

[out] ProfileBufferLength

Zeiger auf eine ULONG , die die Länge des ProfileBuffer-Puffers in Bytes empfängt.

[out] LogonId

Zeiger auf eine LUID-Variable , die die neue Anmelde-ID empfängt, die diese Anmeldesitzung eindeutig identifiziert. Das Authentifizierungspaket ist für die Zuweisung dieser LUID und das Erstellen der LSA-Anmeldesitzung für diese Anmeldung verantwortlich.

[out] SubStatus

Zeiger auf einen NTSTATUS, der den Grund für Fehler aufgrund von Kontoeinschränkungen empfängt. Die in SubStatus zurückgegebenen Werte werden vom Authentifizierungspaket bestimmt.

Im Folgenden sind SubStatus-Werte für die MSV1_0- und Kerberos-Authentifizierungspakete aufgeführt.

Wert	Bedeutung
STATUS_INVALID_LOGON_HOURS	Das Benutzerkonto verfügt über Zeitbeschränkungen und kann derzeit nicht für die Anmeldung verwendet werden.
STATUS_INVALID_WORKSTATION	Das Benutzerkonto verfügt über Arbeitsstationseinschränkungen und kann nicht für die Anmeldung von der aktuellen Arbeitsstation verwendet werden.
STATUS_PASSWORD_EXPIRED	Das Kennwort des Benutzerkontos ist abgelaufen.
STATUS_ACCOUNT_DISABLED	Das Benutzerkonto ist derzeit deaktiviert und kann nicht für die Anmeldung verwendet werden.

Weitere Informationen zu NTSTATUS-Codes finden Sie in der Headerdatei Subauth.h, die im Platform SDK enthalten ist.

[out] TokenInformationType

Zeiger, der die Adresse eines LSA_TOKEN_INFORMATION_TYPE Werts empfängt, der den Typ der Informationen angibt, die für die Aufnahme in das zu erstellende Token zurückgegeben werden. Die Informationen werden mithilfe des TokensInformation-Parameters zurückgegeben.

[out] TokenInformation

Zeiger, der die Adresse der Informationen empfängt, die in das Token eingeschlossen werden sollen. Format und Inhalt von TokenInformation werden durch den TokenInformationType-Parameter angegeben. Ihr Authentifizierungspaket ist für die Zuweisung des von TokenInformation verwendeten Arbeitsspeichers verantwortlich. Dieser Arbeitsspeicher wird jedoch von der LSA freigegeben.

[out] AccountName

Zeiger auf eine LSA_UNICODE_STRING Struktur, die den Namen des Benutzerkontos empfängt. AccountName muss immer zurückgegeben werden, unabhängig vom Erfolg oder Misserfolg des Aufrufs. Seine Zeichenfolge ist im Überwachungsdatensatz für einen Authentifizierungsversuch enthalten. Ihr Authentifizierungspaket ist für die Zuweisung des von AccountName verwendeten Arbeitsspeichers verantwortlich. Es wird von der LSA freigegeben.

[out] AuthenticatingAuthority

Optional. Zeiger auf eine LSA_UNICODE_STRING Struktur, die die Beschreibung der Authentifizierungsautorität für die Anmeldung empfängt. Dieser Parameter kann NULL sein. Diese Zeichenfolge ist im Überwachungsdatensatz für einen Authentifizierungsversuch enthalten. Ihr Authentifizierungspaket ist für die Zuweisung des von AuthenticatingAuthority verwendeten Arbeitsspeichers verantwortlich. Dieser Arbeitsspeicher wird jedoch von der LSA freigegeben.

Das MSV1_0-Authentifizierungspaket gibt den Domänennamen der Domäne zurück, die das Konto überprüft. Das Kerberos-Authentifizierungspaket gibt den NetBIOS-Domänennamen zurück.

[out] MachineName

Optional. Zeiger, der die Adresse einer LSA_UNICODE_STRING-Struktur empfängt, die den Namen der Arbeitsstation des Clients enthält. Diese Informationen sind im Überwachungsdatensatz für einen Authentifizierungsversuch enthalten. Ihr Authentifizierungspaket ist für die Zuweisung des von MachineName verwendeten Arbeitsspeichers verantwortlich. Dieser Arbeitsspeicher wird jedoch von der LSA freigegeben.

Das MSV1_0-Authentifizierungspaket gibt den NetBIOS-Namen der Arbeitsstation des Clients zurück.

Rückgabewert

Wenn die Funktion erfolgreich ist, sollte sie STATUS_SUCCESS zurückgeben.

Andernfalls sollte ein NTSTATUS-Fehlercode zurückgegeben werden, bei dem es sich um einen der folgenden Werte oder einen der Rückgabewerte der LSA-Richtlinienfunktion handeln kann.

Rückgabecode	Beschreibung
STATUS_NO_MEMORY	Die Anmeldung konnte nicht abgeschlossen werden, da das Arbeitsspeicherkontingent des Clients nicht ausreicht, um den Rückgabepuffer zuzuweisen.
STATUS_NO_LOGON_SERVERS	Für die Authentifizierungsanforderung stehen keine Domänencontroller zur Verfügung.
STATUS_LOGON_FAILURE	Der Anmeldeversuch ist fehlgeschlagen. Der Grund für den Fehler ist nicht angegeben. typische Gründe sind falsch geschriebene Benutzernamen und Kennwörter.
STATUS_ACCOUNT_RESTRICTION	Das Benutzerkonto und das Kennwort sind legitim, aber Einschränkungen des Benutzerkontos verhindern eine erfolgreiche Anmeldung zu diesem Zeitpunkt.
STATUS_BAD_VALIDATION_CLASS	Die bereitgestellten Authentifizierungsinformationen werden vom Authentifizierungspaket erkannt.

Aufrufende Anwendungen können die LsaNtStatusToWinError-Funktion verwenden, um den NTSTATUS-Code in einen Windows-Fehlercode zu konvertieren.

Hinweise

Authentifizierungspakete müssen eine der folgenden Funktionen implementieren: LsaApLogonUser, LsaApLogonUserEx oder LsaApLogonUserEx2.

LsaApLogonUserEx wurde für die C2-Zertifizierung hinzugefügt. C2 ist eine Sicherheitsklassifizierung, die von der USA Government definiert wird.

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	ntsecpkg.h