Função LogonUserExExW

A função LogonUserExExW tenta fazer logon de um usuário no computador local. O computador local é o computador do qual LogonUserExExW foi chamado. Você não pode usar LogonUserExExW para fazer logon em um computador remoto. Especifique o usuário usando um nome de usuário e domínio e autentique o usuário usando uma senha de texto não criptografado. Se a função for bem-sucedida, ela 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.

Essa função é semelhante à função LogonUserEx , exceto que ela usa o parâmetro adicional, pTokenGroups, que é um conjunto de um ou mais SIDs ( identificadores de segurança ) que são adicionados ao token retornado ao chamador quando o logon é bem-sucedido.

Essa função não é declarada em um cabeçalho público e não tem nenhuma biblioteca de importação associada. Você deve usar as funções LoadLibrary e GetProcAddress para vincular dinamicamente a Advapi32.dll.

Sintaxe

BOOL WINAPI LogonUserExExW(
  _In_      LPTSTR        lpszUsername,
  _In_opt_  LPTSTR        lpszDomain,
  _In_opt_  LPTSTR        lpszPassword,
  _In_      DWORD         dwLogonType,
  _In_      DWORD         dwLogonProvider,
  _In_opt_  PTOKEN_GROUPS pTokenGroups,
  _Out_opt_ PHANDLE       phToken,
  _Out_opt_ PSID          *ppLogonSid,
  _Out_opt_ PVOID         *ppProfileBuffer,
  _Out_opt_ LPDWORD       pdwProfileLength,
  _Out_opt_ PQUOTA_LIMITS pQuotaLimits
);

Parâmetros

lpszUsername [in]

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 ,o parâmetro lpszDomain deverá ser NULL.

lpszDomain [in, opcional]

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.

lpszPassword [in, opcional]

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.

dwLogonType [in]

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

Valor	Significado
LOGON32_LOGON_INTERACTIVE 2	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 3	Esse tipo de logon destina-se a servidores de alto desempenho para autenticar senhas de texto não criptografado. A função LogonUserExExW não armazena em cache as credenciais desse tipo de logon.
LOGON32_LOGON_BATCH 4	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 LogonUserExExW não armazena em cache as credenciais desse tipo de logon.
LOGON32_LOGON_SERVICE 5	Indica um logon de tipo de serviço. A conta fornecida deve ter o privilégio de serviço habilitado.
LOGON32_LOGON_UNLOCK 7	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.
LOGON32_LOGON_NETWORK_CLEARTEXT 8	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 LogonUserExExW, verificar se o usuário pode acessar o sistema pela rede e ainda se comunicar com outros servidores.
LOGON32_LOGON_NEW_CREDENTIALS 9	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.

 

dwLogonProvider [in]

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.

 

pTokenGroups [in, opcional]

Um ponteiro para uma estrutura TOKEN_GROUPS que especifica uma lista de SIDs de grupo que são adicionados ao token que essa função recebe após o logon bem-sucedido. Todos os SIDs adicionados ao token também afetam a expansão do grupo. Por exemplo, se os SIDs adicionados forem membros de grupos locais, esses grupos também serão adicionados ao token de acesso recebido.

Se esse parâmetro não for NULL, o chamador dessa função deverá ter o privilégio SE_TCB_PRIVILEGE concedido e habilitado.

phToken [out, opcional]

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, LogonUserExExW 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 .

ppLogonSid [out, opcional]

Um ponteiro para um ponteiro para um SID que recebe o SID do usuário conectado.

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

ppProfileBuffer [out, opcional]

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

pdwProfileLength [out, opcional]

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

pQuotaLimits [out, opcional]

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

Valor retornado

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.

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 o parâmetro opcional pTokenGroups for fornecido, o LSA não adicionará o SID local nem o SID de logon automaticamente.

Requisitos

Confira também

Controle de Acesso cliente/servidor

Funções de Controle de Acesso cliente/servidor

CloseHandle

Createprocessasuser

DuplicateTokenEx

Impersonateloggedonuser

LogonUserEx

QUOTA_LIMITS