Função CheckTokenMembership (securitybaseapi.h)

Artigo
08/25/2023

A função CheckTokenMembership determina se um SID ( identificador de segurança ) especificado está habilitado em um token de acesso. Se você quiser determinar a associação de grupo para tokens de contêiner de aplicativo, precisará usar a função CheckTokenMembershipEx .

Sintaxe

BOOL CheckTokenMembership(
  [in, optional] HANDLE TokenHandle,
  [in]           PSID   SidToCheck,
  [out]          PBOOL  IsMember
);

Parâmetros

[in, optional] TokenHandle

Um identificador para um token de acesso. O identificador deve ter TOKEN_QUERY acesso ao token. O token deve ser um token de representação.

Se TokenHandle for NULL, CheckTokenMembership usará o token de representação do thread de chamada. Se o thread não estiver representando, a função duplicará o token primário do thread para criar um token de representação.

[in] SidToCheck

Um ponteiro para uma estrutura SID . A função CheckTokenMembership verifica a presença desse SID nos SIDs de usuário e grupo do token de acesso.

[out] IsMember

Um ponteiro para uma variável que recebe os resultados do marcar. Se o SID estiver presente e tiver o atributo SE_GROUP_ENABLED, IsMember retornará TRUE; caso contrário, retornará FALSE.

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 função CheckTokenMembership simplifica o processo de determinar se um SID está presente e habilitado em um token de acesso.

Mesmo que um SID esteja presente no token, o sistema pode não usar o SID em um marcar de acesso. O SID pode estar desabilitado ou ter o atributo SE_GROUP_USE_FOR_DENY_ONLY . O sistema usa apenas SIDs habilitados para conceder acesso ao executar um marcar de acesso. Para obter mais informações, consulte Atributos sid em um token de acesso.

Se TokenHandle for um token restrito ou se TokenHandle for NULL e o token efetivo atual do thread de chamada for um token restrito, CheckTokenMembership também verificará se o SID está presente na lista de SIDs restritos.

Exemplos

O exemplo a seguir mostra a verificação de um token para associação no grupo local Administradores.

BOOL IsUserAdmin(VOID)
/*++ 
Routine Description: This routine returns TRUE if the caller's
process is a member of the Administrators local group. Caller is NOT
expected to be impersonating anyone and is expected to be able to
open its own process and process token. 
Arguments: None. 
Return Value: 
   TRUE - Caller has Administrators local group. 
   FALSE - Caller does not have Administrators local group. --
*/ 
{
    BOOL b;
    SID_IDENTIFIER_AUTHORITY NtAuthority = SECURITY_NT_AUTHORITY;
    PSID AdministratorsGroup;
    b = AllocateAndInitializeSid(
        &NtAuthority,
        2,
        SECURITY_BUILTIN_DOMAIN_RID,
        DOMAIN_ALIAS_RID_ADMINS,
        0, 0, 0, 0, 0, 0,
        &AdministratorsGroup );

    if(b)
    {
        if (!CheckTokenMembership( NULL, AdministratorsGroup, &b))
        {
             b = FALSE;
        }
        FreeSid(AdministratorsGroup);
    }

    return(b);
}

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll