Función LogonUserExA (winbase.h)

Artículo
11/20/2024

La función LogonUserEx intenta iniciar sesión de un usuario en el equipo local. El equipo local es el equipo desde el que se llamó a logonUserEx. No puede usar LogonUserEx para iniciar sesión en un equipo remoto. Especifique el usuario con un nombre de usuario y un dominio y autenticar el usuario con una contraseña de texto no cifrado. Si la función se realiza correctamente, recibirá un identificador para un token que representa al usuario que ha iniciado sesión. A continuación, puede usar este identificador de token para suplantar al usuario especificado o, en la mayoría de los casos, para crear un proceso de que se ejecuta en el contexto del usuario especificado.

Sintaxis

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

Parámetros

[in] lpszUsername

Puntero a una cadena terminada en NULL que especifica el nombre del usuario. Este es el nombre de la cuenta de usuario en la que iniciar sesión. Si usa el formato nombre principal de usuario (UPN), user@DNS_domain_name, el parámetro lpszDomain debe ser NULL.

[in, optional] lpszDomain

Puntero a una cadena terminada en null que especifica el nombre del dominio o servidor cuya base de datos de cuenta contiene el lpszUsername cuenta. Si este parámetro es NULL, el nombre de usuario debe especificarse en formato UPN. Si este parámetro es ".", la función valida la cuenta con solo la base de datos de la cuenta local.

[in, optional] lpszPassword

Puntero a una cadena terminada en null que especifica la contraseña de texto no cifrado de la cuenta de usuario especificada por lpszUsername. Cuando haya terminado de usar la contraseña, borre la contraseña de la memoria llamando a la función SecureZeroMemory. Para obtener más información sobre cómo proteger contraseñas, consulte Control de contraseñas.

[in] dwLogonType

Tipo de operación de inicio de sesión que se va a realizar. Este parámetro puede ser uno de los siguientes valores.

Valor	Significado
LOGON32_LOGON_BATCH	Este tipo de inicio de sesión está pensado para servidores por lotes, donde los procesos se pueden ejecutar en nombre de un usuario sin su intervención directa. Este tipo también es para servidores de mayor rendimiento que procesan muchos intentos de autenticación de texto no cifrado a la vez, como el correo o los servidores web. La función LogonUserEx no almacena en caché las credenciales de este tipo de inicio de sesión.
LOGON32_LOGON_INTERACTIVE	Este tipo de inicio de sesión está pensado para los usuarios que van a usar interactivamente el equipo, como un usuario que inicia sesión mediante un terminal de servidor, shell remoto o proceso similar. Este tipo de inicio de sesión tiene el gasto adicional de almacenar en caché información de inicio de sesión para las operaciones desconectadas; por lo tanto, es inapropiado para algunas aplicaciones cliente/servidor, como un servidor de correo.
LOGON32_LOGON_NETWORK	Este tipo de inicio de sesión está diseñado para servidores de alto rendimiento para autenticar contraseñas de texto no cifrado. La función LogonUserEx no almacena en caché las credenciales de este tipo de inicio de sesión.
LOGON32_LOGON_NETWORK_CLEARTEXT	Este tipo de inicio de sesión conserva el nombre y la contraseña en el paquete de autenticación de , lo que permite al servidor realizar conexiones a otros servidores de red al suplantar al cliente. Un servidor puede aceptar credenciales de texto no cifrado de un cliente, llamar a LogonUserEx, comprobar que el usuario puede acceder al sistema a través de la red y seguir comunicándose con otros servidores.
LOGON32_LOGON_NEW_CREDENTIALS	Este tipo de inicio de sesión permite al autor de la llamada clonar su token actual y especificar nuevas credenciales para las conexiones salientes. La nueva sesión de inicio de sesión tiene el mismo identificador local, pero usa credenciales diferentes para otras conexiones de red. Este tipo de inicio de sesión solo es compatible con el proveedor de inicio de sesión de LOGON32_PROVIDER_WINNT50.
LOGON32_LOGON_SERVICE	Indica un inicio de sesión de tipo de servicio. La cuenta proporcionada debe tener habilitado el privilegio de servicio.
LOGON32_LOGON_UNLOCK	Este tipo de inicio de sesión es para archivos DLL de GINA que inician sesión en los usuarios que usarán interactivamente el equipo. Este tipo de inicio de sesión puede generar un registro de auditoría único que muestre cuándo se desbloqueó la estación de trabajo.

[in] dwLogonProvider

Proveedor de inicio de sesión. Este parámetro puede ser uno de los siguientes valores.

Valor	Significado
LOGON32_PROVIDER_DEFAULT	Use el proveedor de inicio de sesión estándar para el sistema. El proveedor de seguridad predeterminado es NTLM.
LOGON32_PROVIDER_WINNT50	Use el proveedor de inicio de sesión de negotiate.
LOGON32_PROVIDER_WINNT40	Use el proveedor de inicio de sesión NTLM.

[out, optional] phToken

Puntero a una variable de identificador que recibe un identificador a un token que representa al usuario especificado.

Puede usar el identificador devuelto en las llamadas a la función ImpersonateLoggedOnUser.

En la mayoría de los casos, el identificador devuelto es un token principal que puede usar en llamadas a la función CreateProcessAsUser de . Sin embargo, si especifica la marca LOGON32_LOGON_NETWORK, LogonUserEx devuelve un token de suplantación que no puede usar en CreateProcessAsUser a menos que llame a DuplicateTokenEx para convertir el token de suplantación en un token principal.

Cuando ya no necesite este identificador, ciérralo llamando a la función CloseHandle.

[out, optional] ppLogonSid

Puntero a un puntero a un identificador de seguridad (SID) que recibe el SID del usuario que inició sesión.

Cuando haya terminado de usar el SID, puede liberarlo llamando a la función localFree .

[out, optional] ppProfileBuffer

Puntero a un puntero que recibe la dirección de un búfer que contiene el perfil del usuario que ha iniciado sesión.

[out, optional] pdwProfileLength

Puntero a un DWORD que recibe la longitud del búfer de perfil.

[out, optional] pQuotaLimits

Puntero a una estructura de QUOTA_LIMITS que recibe información sobre las cuotas del usuario que ha iniciado sesión.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Observaciones

El tipo de inicio de sesión de LOGON32_LOGON_NETWORK es más rápido, pero tiene las siguientes limitaciones:

La función devuelve un token de suplantación , no un token principal. No puede usar este token directamente en la función createProcessAsUser . Sin embargo, puede llamar a la función DuplicateTokenEx para convertir el token en un token principal y, a continuación, usarlo en CreateProcessAsUser.
Si convierte el token en un token principal y lo usa en CreateProcessAsUser para iniciar un proceso, el nuevo proceso no puede acceder a otros recursos de red, como servidores remotos o impresoras, a través del redirector. Una excepción es que si el recurso de red no está controlado por el acceso, el nuevo proceso podrá acceder a él.

El privilegio SE_TCB_NAME no es necesario para esta función a menos que inicie sesión en una cuenta de Passport.

La cuenta especificada por lpszUsername debe tener los derechos de cuenta necesarios. Por ejemplo, para iniciar sesión en un usuario con la marca LOGON32_LOGON_INTERACTIVE, el usuario (o un grupo al que pertenece el usuario) debe tener derecho a la cuenta de SE_INTERACTIVE_LOGON_NAME. Para obtener una lista de los derechos de cuenta que afectan a las distintas operaciones de inicio de sesión, consulte Derechos de acceso a objetos de cuenta.

Un usuario se considera que ha iniciado sesión si existe al menos un token. Si llama a createProcessAsUser y, a continuación, cierra el token, el usuario sigue iniciando sesión hasta que finalice el proceso (y todos los procesos secundarios).

Si la llamada logonUserEx se realiza correctamente, el sistema notifica a los proveedores de red que se produjo el inicio de sesión llamando a la función de punto de entrada NPLogonNot ify del proveedor.

Nota

El encabezado winbase.h define LogonUserEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winbase.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll