Função LogonUserA (winbase.h)
A função LogonUser tenta registrar um usuário no computador local. O computador local é o computador do qual LogonUser foi chamado. Você não pode usar LogonUser 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 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
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),DNSDomainName do usuário@, 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 ser um dos seguintes valores, definidos em Winbase.h.
| 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. |
|
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 LogonUser 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 LogonUser, 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. Observação: a partir de janeiro de 2023, não é possível usar o tipo de logon LOGON32_LOGON_NEW_CREDENTIALS com uma gMSA (Conta de Serviço Gerenciado de Grupo). |
|
Indica um logon de tipo de serviço. A conta fornecida deve ter o privilégio de serviço habilitado. |
|
Não há mais suporte para GINAs.
Windows Server 2003 e Windows XP: 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
Especifica 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 é negociar, a menos que você passe NULL para o nome de domínio e o nome de usuário não esteja no formato UPN. Nesse caso, o provedor padrão é NTLM. |
|
Use o provedor de logon negotiate. |
|
Use o provedor de logon NTLM. |
[out] 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, LogonUser retornará um token de representação que não poderá ser usado em CreateProcessAsUser , a menos que você chame DuplicateTokenEx para convertê-lo em um token primário.
Quando você não precisar mais desse identificador, feche-o chamando a função CloseHandle .
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 Constantes de direitos de conta.
Um usuário será considerado conectado se houver pelo menos um token. Se você chamar CreateProcessAsUser e fechar o token, o sistema considerará o usuário como ainda conectado até que o processo (e todos os processos filho) sejam encerrados.
Se a chamada logonUser 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.
Exemplos
Você pode gerar um token LocalService usando o código a seguir.
LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)
Observação
O cabeçalho winbase.h define LogonUser 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