Função ImpersonateLoggedOnUser (securitybaseapi.h)

Artigo
03/13/2024

A função ImpersonateLoggedOnUser permite que o thread de chamada represente o contexto de segurança de um usuário conectado. O usuário é representado por um identificador de token.

Sintaxe

BOOL ImpersonateLoggedOnUser(
  [in] HANDLE hToken
);

Parâmetros

[in] hToken

Um identificador para um token de acesso primário ou de representação que representa um usuário conectado. Esse pode ser um identificador de token retornado por uma chamada para as funções LogonUser, CreateRestrictedToken, DuplicateToken, DuplicateTokenEx, OpenProcessToken ou OpenThreadToken . Se hToken for um identificador para um token primário, o token deverá ter acesso TOKEN_QUERY e TOKEN_DUPLICATE . Se hToken for um identificador para um token de representação, o token deverá ter acesso TOKEN_QUERY e TOKEN_IMPERSONATE .

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A representação dura até que o thread seja encerrado ou até que chame RevertToSelf.

O thread de chamada não precisa ter privilégios específicos para chamar ImpersonateLoggedOnUser.

Se a chamada para ImpersonateLoggedOnUser falhar, a conexão do cliente não será representada e a solicitação do cliente será feita no contexto de segurança do processo. Se o processo estiver em execução como uma conta altamente privilegiada, como LocalSystem ou como membro de um grupo administrativo, o usuário poderá executar ações que, de outra forma, não seriam permitidas. Portanto, é importante sempre marcar o valor retornado da chamada e, se ela falhar, gerar um erro; não continuar a execução da solicitação do cliente.

Todas as funções de representação, incluindo ImpersonateLoggedOnUser , permitem a representação solicitada se uma das seguintes opções for verdadeira:

O nível de representação solicitado do token é menor que SecurityImpersonation, como SecurityIdentification ou SecurityAnonymous.
O chamador tem o privilégio SeImpersonatePrivilege .
Um processo (ou outro processo na sessão de logon do chamador) criou o token usando credenciais explícitas por meio da função LogonUser ou LsaLogonUser .
A identidade autenticada é a mesma que o chamador.

Windows XP com SP1 e versões anteriores: Não há suporte para o privilégio SeImpersonatePrivilege .

Para obter mais informações sobre representação, consulte Representação de cliente.

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	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll