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

Artículo
03/08/2023

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

Esta función se llama solo para el inicio de sesión inicial de un usuario. Las solicitudes de autenticación posteriores deben usar LsaCallAuthenticationPackage.

Si LsaApLogonUser se realiza correctamente, crea una sesión de inicio de sesión. También devuelve información utilizada para compilar el token que representa al usuario que acaba de iniciar sesión.

Sintaxis

LSA_AP_LOGON_USER LsaApLogonUser;

NTSTATUS LsaApLogonUser(
  [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] PLSA_UNICODE_STRING *AccountName,
  [out] PLSA_UNICODE_STRING *AuthenticatingAuthority
)
{...}

Parámetros

[in] ClientRequest

Puntero a un búfer de LSA_CLIENT_REQUEST opaco que representa la solicitud del cliente LSA. El paquete de autenticación puede pasar este valor a AllocateClientBuffer y FreeClientBuffer para identificar el proceso de cliente en el que se debe asignar o liberar la memoria.

[in] LogonType

Valor de SECURITY_LOGON_TYPE que identifica el tipo de inicio de sesión solicitado.

[in] AuthenticationInformation

Proporciona la información de autenticación específica del paquete de autenticación. El LSA liberará este búfer. Este es el mismo búfer de entrada pasado a LsaLogonUser.

[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, en bytes, 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 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 un 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 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 .

En la tabla siguiente se enumeran 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; 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; no se puede usar para iniciar sesión en 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.

La función LsaNtStatusToWinError convierte un código NTSTATUS en un código de error de Windows.

[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 en el búfer TokenInformation .

[out] TokenInformation

Puntero que recibe información que se va a incluir en el token. El formato y el contenido del búfer 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; sin embargo, la LSA liberará esta memoria.

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

Valor devuelto

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

Si se produce un error en la función, debe devolver un código de error NTSTATUS, que puede ser uno de los valores siguientes 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 eran legítimas, pero las restricciones de la cuenta de usuario impiden el inicio de sesión en este momento. Para obtener más información, consulte el parámetro SubStatus .
STATUS_BAD_VALIDATION_CLASS	El paquete de autenticación especificado no 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.

Requisitos


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