Função LogonUserExW (winbase.h)
A função LogonUserEx tenta registrar 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, criar um processo executado no contexto do usuário especificado.
Sintaxe
BOOL LogonUserExW(
[in] LPCWSTR lpszUsername,
[in, optional] LPCWSTR lpszDomain,
[in, optional] LPCWSTR 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 de 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, desmarque 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 lote, em que os processos podem estar sendo executados em nome de um usuário sem a intervenção direta. Esse tipo também é para servidores de alto desempenho que processam muitas tentativas de autenticação de texto sem formatação por vez, como servidores Web ou email. A função LogonUserEx não armazena credenciais em cache para esse tipo de logon. |
|
Esse tipo de logon destina-se a usuários que usarão interativamente o computador, como um usuário 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 sem formatação. A função LogonUserEx não armazena credenciais em cache para esse 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 enquanto representa o cliente. Um servidor pode aceitar credenciais de texto sem formatação de um cliente, chamar LogonUserEx, verificar se o usuário pode acessar o sistema em toda a 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 em 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 você 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 de 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 SE_INTERACTIVE_LOGON_NAME conta. Para obter uma lista dos direitos de conta que afetam as várias operações de logon, consulte Direitos de Acesso ao Objeto 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) sejam encerrados.
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 (incluir Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |
Confira também
Controle de Acesso cliente/servidor
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de