Compartilhar via


Função LogonUserExA (winbase.h)

A função LogonUserEx tenta fazer logon de um usuário no computador local. O computador local é o computador do qual LogonUserEx foi chamado. Você não pode usar LogonUserEx para fazer logon em um computador remoto. Especifique o usuário com um nome de usuário e domínio e autentique o usuário com uma senha de texto não criptografado. Se a função for bem-sucedida, você receberá um identificador para um token que representa o usuário conectado. Em seguida, você pode usar esse identificador de token para representar o usuário especificado ou, na maioria dos casos, para criar um processo executado no contexto do usuário especificado.

Sintaxe

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

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do usuário. Esse é o nome da conta de usuário na qual fazer logon. Se você usar o formato UPN ( nome upn ), user@DNS_domain_name, o parâmetro lpszDomain deverá ser NULL.

[in, optional] lpszDomain

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do domínio ou servidor cujo banco de dados de conta contém a conta lpszUsername . Se esse parâmetro for NULL, o nome de usuário deverá ser especificado no formato UPN. Se esse parâmetro for ".", a função validará a conta usando apenas o banco de dados da conta local.

[in, optional] lpszPassword

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica a senha de texto não criptografado para a conta de usuário especificada por lpszUsername. Quando terminar de usar a senha, limpe a senha da memória chamando a função SecureZeroMemory . Para obter mais informações sobre como proteger senhas, consulte Manipulando senhas.

[in] dwLogonType

O tipo de operação de logon a ser executada. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
LOGON32_LOGON_BATCH
Esse tipo de logon destina-se a servidores em lotes, em que os processos podem estar sendo executados em nome de um usuário sem sua intervenção direta. Esse tipo também é para servidores de alto desempenho que processam muitas tentativas de autenticação de texto não criptografado por vez, como servidores Web ou de email. A função LogonUserEx não armazena em cache as credenciais desse tipo de logon.
LOGON32_LOGON_INTERACTIVE
Esse tipo de logon destina-se a usuários que usarão interativamente o computador, como um usuário que está sendo conectado por um servidor de terminal , shell remoto ou processo semelhante. Esse tipo de logon tem a despesa adicional de armazenar em cache informações de logon para operações desconectadas; portanto, é inadequado para alguns aplicativos cliente/servidor, como um servidor de email.
LOGON32_LOGON_NETWORK
Esse tipo de logon destina-se a servidores de alto desempenho para autenticar senhas de texto não criptografado. A função LogonUserEx não armazena em cache as credenciais desse tipo de logon.
LOGON32_LOGON_NETWORK_CLEARTEXT
Esse tipo de logon preserva o nome e a senha no pacote de autenticação, o que permite que o servidor faça conexões com outros servidores de rede ao representar o cliente. Um servidor pode aceitar credenciais de texto não criptografado de um cliente, chamar LogonUserEx, verificar se o usuário pode acessar o sistema pela rede e ainda se comunicar com outros servidores.
LOGON32_LOGON_NEW_CREDENTIALS
Esse tipo de logon permite que o chamador clone seu token atual e especifique novas credenciais para conexões de saída. A nova sessão de logon tem o mesmo identificador local, mas usa credenciais diferentes para outras conexões de rede.

Esse tipo de logon tem suporte apenas pelo provedor de logon LOGON32_PROVIDER_WINNT50.

LOGON32_LOGON_SERVICE
Indica um logon de tipo de serviço. A conta fornecida deve ter o privilégio de serviço habilitado.
LOGON32_LOGON_UNLOCK
Esse tipo de logon é para DLLs GINA que fazem logon de usuários que usarão interativamente o computador. Esse tipo de logon pode gerar um registro de auditoria exclusivo que mostra quando a estação de trabalho foi desbloqueada.

[in] dwLogonProvider

O provedor de logon. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
LOGON32_PROVIDER_DEFAULT
Use o provedor de logon padrão para o sistema. O provedor de segurança padrão é NTLM.
LOGON32_PROVIDER_WINNT50
Use o provedor de logon negotiate.
LOGON32_PROVIDER_WINNT40
Use o provedor de logon NTLM.

[out, optional] phToken

Um ponteiro para uma variável de identificador que recebe um identificador para um token que representa o usuário especificado.

Você pode usar o identificador retornado em chamadas para a função ImpersonateLoggedOnUser .

Na maioria dos casos, o identificador retornado é um token primário que você pode usar em chamadas para a função CreateProcessAsUser . No entanto, se você especificar o sinalizador LOGON32_LOGON_NETWORK, LogonUserEx retornará um token de representação que não poderá ser usado em CreateProcessAsUser , a menos que chame DuplicateTokenEx para converter o token de representação em um token primário.

Quando você não precisar mais desse identificador, feche-o chamando a função CloseHandle .

[out, optional] ppLogonSid

Um ponteiro para um ponteiro para um SID ( identificador de segurança ) que recebe o SID do usuário conectado.

Quando terminar de usar o SID, libere-o chamando a função LocalFree .

[out, optional] ppProfileBuffer

Um ponteiro para um ponteiro que recebe o endereço de um buffer que contém o perfil do usuário conectado.

[out, optional] pdwProfileLength

Um ponteiro para um DWORD que recebe o comprimento do buffer de perfil.

[out, optional] pQuotaLimits

Um ponteiro para uma estrutura QUOTA_LIMITS que recebe informações sobre as cotas para o usuário conectado.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O tipo de logon LOGON32_LOGON_NETWORK é mais rápido, mas tem as seguintes limitações:

  • A função retorna um token de representação, não um token primário. Você não pode usar esse token diretamente na função CreateProcessAsUser . No entanto, você pode chamar a função DuplicateTokenEx para converter o token em um token primário e usá-lo em CreateProcessAsUser.
  • Se você converter o token em um token primário e usá-lo em CreateProcessAsUser para iniciar um processo, o novo processo não poderá acessar outros recursos de rede, como servidores remotos ou impressoras, por meio do redirecionador. Uma exceção é que, se o recurso de rede não for controlado por acesso, o novo processo poderá acessá-lo.

O privilégio SE_TCB_NAME não é necessário para essa função, a menos que você esteja fazendo logon em uma conta do Passport.

A conta especificada por lpszUsername deve ter os direitos de conta necessários. Por exemplo, para fazer logon em um usuário com o sinalizador LOGON32_LOGON_INTERACTIVE, o usuário (ou um grupo ao qual o usuário pertence) deve ter o direito de conta SE_INTERACTIVE_LOGON_NAME. Para obter uma lista dos direitos de conta que afetam as várias operações de logon, consulte Direitos de acesso a objetos de conta.

Um usuário será considerado conectado se houver pelo menos um token. Se você chamar CreateProcessAsUser e fechar o token, o usuário ainda estará conectado até que o processo (e todos os processos filho) tenham terminado.

Se a chamada LogonUserEx for bem-sucedida, o sistema notificará os provedores de rede de que o logon ocorreu chamando a função de ponto de entrada NPLogonNotify do provedor.

Observação

O cabeçalho winbase.h define LogonUserEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winbase.h (inclua Windows.h)
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Controle de Acesso cliente/servidor

Funções de Controle de Acesso de cliente/servidor

CloseHandle

Createprocessasuser

DuplicateTokenEx

Impersonateloggedonuser

QUOTA_LIMITS