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 um domínio e
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 de nome de entidade de usuário
[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 sem formatação 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 lotes, em que os processos podem estar sendo executados em nome de um usuário sem a intervenção direta. Esse tipo também destina-se a 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 terminal servidor, 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 ao representar 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 do 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 de 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
Especifica o provedor de logon. Esse parâmetro pode ser um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Use o provedor de logon padrão para o sistema. O provedor de segurança padrão é negociado, 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 de negociação. |
|
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
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 de LOGON32_LOGON_NETWORK, logonUser retornará um token de representação que você não pode usar 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
Valor de retorno
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.
Observações
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 no 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 pelo 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 de 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) tenham terminado.
Se a chamada LogonUser for bem-sucedida, o sistema notificará os provedores de rede de que o logon ocorreu chamando o NPLogonNotify do provedor função de ponto de entrada.
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)
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winbase.h (inclua Windows.h) |
| biblioteca | Advapi32.lib |
| de DLL |
Advapi32.dll |
Consulte também
de controle de acesso de cliente/servidor
Funções de controle de acesso de cliente/servidor
DuplicateTokenEx