LSA_AP_LOGON_USER_EX función de devolución de llamada (ntsecpkg.h)

Artículo
08/25/2023

Autentica las credenciales de inicio de sesión de un usuario.

La autoridad de seguridad local (LSA) llama a esta función solo para el inicio de sesión inicial de un usuario. Las solicitudes de autenticación posteriores deben usar LsaCallAuthenticationPackage. Si LsaApLogonUserEx se realiza correctamente, crea una sesión de inicio de sesión y devuelve información utilizada para compilar el token que representa al usuario que acaba de iniciar sesión.

Esta función difiere de LsaApLogonUser en que el nombre de la máquina se agrega al registro de auditoría para el intento de inicio de sesión.

Sintaxis

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
)
{...}

Parámetros

[in] ClientRequest

Puntero a un tipo de datos opaco LSA_CLIENT_REQUEST que representa la solicitud del cliente LSA.

[in] LogonType

Estructura SECURITY_LOGON_TYPE que identifica el tipo de inicio de sesión que se está intentando.

[in] AuthenticationInformation

Proporciona la información de autenticación específica del paquete de autenticación. El LSA liberará este búfer.

[in] ClientAuthenticationBase

Proporciona la dirección de la información de autenticación dentro del proceso de cliente. Esto puede ser necesario para reasignar los punteros dentro del búfer AuthenticationInformation .

[in] AuthenticationInformationLength

Indica la longitud del búfer AuthenticationInformation .

[out] ProfileBuffer

Puntero que recibe la dirección del búfer de perfil en el proceso de cliente. El paquete de autenticación es responsable de asignar el búfer ProfileBuffer dentro del proceso de cliente mediante una llamada a la función AllocateClientBuffer . Sin embargo, si el LSA encuentra posteriormente un error que impide un inicio de sesión correcto, el LSA se encargará de liberar este búfer.

El paquete de autenticación determina el contenido de este búfer. El LSA no modifica este búfer; simplemente devuelve el valor a la función LsaLogonUser .

[out] ProfileBufferLength

Puntero a un ULONG que recibe la longitud del búfer ProfileBuffer , en bytes.

[out] LogonId

Puntero a una variable LUID que recibe el nuevo identificador de inicio de sesión que identifica de forma única esta sesión de inicio de sesión. El paquete de autenticación es responsable de asignar este LUID y de crear la sesión de inicio de sesión de LSA para este inicio de sesión.

[out] SubStatus

Puntero a un NTSTATUS que recibe el motivo de los errores debido a restricciones de cuenta. El paquete de autenticación determina los valores devueltos en SubStatus .

A continuación se muestran los valores de SubStatus para los paquetes de autenticación MSV1_0 y Kerberos.

Valor	Significado
STATUS_INVALID_LOGON_HOURS	La cuenta de usuario tiene restricciones de tiempo y no se puede usar para iniciar sesión en este momento.
STATUS_INVALID_WORKSTATION	La cuenta de usuario tiene restricciones de estación de trabajo y no se puede usar para iniciar sesión desde la estación de trabajo actual.
STATUS_PASSWORD_EXPIRED	La contraseña de la cuenta de usuario ha expirado.
STATUS_ACCOUNT_DISABLED	La cuenta de usuario está deshabilitada actualmente y no se puede usar para iniciar sesión.

Puede encontrar más información sobre los códigos NTSTATUS en el archivo de encabezado Subauth.h incluido con platform SDK.

[out] TokenInformationType

Puntero que recibe la dirección de un valor de LSA_TOKEN_INFORMATION_TYPE que indica el tipo de información devuelta para su inclusión en el token que se va a crear. La información se devuelve mediante el parámetro TokenInformation .

[out] TokenInformation

Puntero que recibe la dirección de información que se va a incluir en el token. El formato y el contenido de TokenInformation se indican mediante el parámetro TokenInformationType . El paquete de autenticación es responsable de asignar la memoria utilizada por TokenInformation; sin embargo, la LSA liberará esta memoria.

[out] AccountName

Puntero a una estructura de LSA_UNICODE_STRING que recibe el nombre de la cuenta de usuario. AccountName siempre debe devolverse independientemente del éxito o error de la llamada; su cadena se incluye en el registro de auditoría para un intento de autenticación. El paquete de autenticación es responsable de asignar la memoria utilizada por AccountName . La LSA liberará.

[out] AuthenticatingAuthority

Opcional. Puntero a una estructura de LSA_UNICODE_STRING que recibe la descripción de la autoridad de autenticación para el inicio de sesión. Este parámetro puede ser NULL. Esta cadena se incluye en el registro de auditoría para un intento de autenticación. El paquete de autenticación es responsable de asignar la memoria utilizada por AuthenticatingAuthority; sin embargo, la LSA liberará esta memoria.

El paquete de autenticación MSV1_0 devuelve el nombre de dominio del dominio que valida la cuenta. El paquete de autenticación Kerberos devuelve el nombre de dominio NetBIOS.

[out] MachineName

Opcional. Puntero que recibe la dirección de una estructura de LSA_UNICODE_STRING que contiene el nombre de la estación de trabajo del cliente. Esta información se incluye en el registro de auditoría para un intento de autenticación. El paquete de autenticación es responsable de asignar la memoria utilizada por MachineName; sin embargo, la LSA liberará esta memoria.

El paquete de autenticación MSV1_0 devuelve el nombre NetBIOS de la estación de trabajo del cliente.

Valor devuelto

Si la función se realiza correctamente, debe devolver STATUS_SUCCESS.

De lo contrario, debe devolver un código de error NTSTATUS, que puede ser uno de los siguientes valores o uno de los valores devueltos de la función de directiva LSA.

Código devuelto	Descripción
STATUS_NO_MEMORY	No se pudo completar el inicio de sesión porque la cuota de memoria del cliente no es suficiente para asignar el búfer de devolución.
STATUS_NO_LOGON_SERVERS	No hay controladores de dominio disponibles para atender la solicitud de autenticación.
STATUS_LOGON_FAILURE	Error en el intento de inicio de sesión. No se especifica el motivo del error; Entre los motivos típicos se incluyen los nombres de usuario y las contraseñas mal escritos.
STATUS_ACCOUNT_RESTRICTION	La cuenta de usuario y la contraseña son legítimas, pero las restricciones de la cuenta de usuario impiden el inicio de sesión correcto en este momento.
STATUS_BAD_VALIDATION_CLASS	El paquete de autenticación reconoce la información de autenticación proporcionada.

Las aplicaciones que llaman pueden usar la función LsaNtStatusToWinError para convertir el código NTSTATUS en un código de error de Windows.

Comentarios

Los paquetes de autenticación deben implementar una de las siguientes funciones: LsaApLogonUser, LsaApLogonUserEx o LsaApLogonUserEx2.

LsaApLogonUserEx se agregó para la certificación C2. C2 es una clasificación de seguridad definida por el gobierno Estados Unidos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ntsecpkg.h