Función LogonUserA (winbase.h)

Artículo
03/03/2024

La función LogonUser intenta registrar un usuario en el equipo local. El equipo local es el equipo desde el que se llamó a LogonUser . No puede usar LogonUser para iniciar sesión en un equipo remoto. Especifique el usuario con un nombre de usuario y un dominio y autentique al usuario con una contraseña de texto no cifrado . Si la función se ejecuta 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 que se ejecute en el contexto del usuario especificado.

Sintaxis

BOOL LogonUserA(
  [in]           LPCSTR  lpszUsername,
  [in, optional] LPCSTR  lpszDomain,
  [in, optional] LPCSTR  lpszPassword,
  [in]           DWORD   dwLogonType,
  [in]           DWORD   dwLogonProvider,
  [out]          PHANDLE phToken
);

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 de nombre principal de usuario (UPN), User@DNSDomainName, 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 la cuenta lpszUsername . 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 usando 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, desactive la contraseña de la memoria llamando a la función SecureZeroMemory . Para obtener más información sobre cómo proteger las 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, definidos en Winbase.h.

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 los servidores de correo o web.
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 servidor de terminal , un shell remoto o un 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, no es adecuado para algunas aplicaciones cliente/servidor, como un servidor de correo.
LOGON32_LOGON_NETWORK	Este tipo de inicio de sesión está pensado para servidores de alto rendimiento para autenticar contraseñas de texto no cifrado. La función LogonUser 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, 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 LogonUser, 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. Nota: A partir de enero de 2023, no es posible usar el tipo de inicio de sesión de LOGON32_LOGON_NEW_CREDENTIALS con una cuenta de servicio administrada de grupo (gMSA).
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	Las GGA ya no se admiten. Windows Server 2003 y Windows XP: 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 muestra cuándo se desbloqueó la estación de trabajo.

[in] dwLogonProvider

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

Valor	Significado
LOGON32_PROVIDER_DEFAULT	Use el proveedor de inicio de sesión estándar para el sistema. El proveedor de seguridad predeterminado es negotiate, a menos que pase NULL para el nombre de dominio y el nombre de usuario no esté en formato UPN. En este caso, el proveedor 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] 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 . Sin embargo, si especifica la marca de LOGON32_LOGON_NETWORK, LogonUser devuelve un token de suplantación que no puede usar en CreateProcessAsUser a menos que llame a DuplicateTokenEx para convertirlo en un token principal.

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

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.

Comentarios

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 Constantes de derechos de cuenta.

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

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

Ejemplos

Puede generar un token de LocalService mediante el código siguiente.

LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)

Nota

El encabezado winbase.h define LogonUser 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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	winbase.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll