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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Indica um logon de tipo de serviço. A conta fornecida deve ter o privilégio de serviço habilitado. |
|
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 |
|---|---|
|
Use o provedor de logon padrão para o sistema. O provedor de segurança padrão é NTLM. |
|
Use o provedor de logon negotiate. |
|
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