Expand Minimize

CheckTokenMembership function

The CheckTokenMembership function determines whether a specified security identifier (SID) is enabled in an access token. If you want to determine group membership for app container tokens, you need to use the CheckTokenMembershipEx function.

Syntax


BOOL WINAPI CheckTokenMembership(
  _In_opt_  HANDLE TokenHandle,
  _In_      PSID SidToCheck,
  _Out_     PBOOL IsMember
);

Parameters

TokenHandle [in, optional]

A handle to an access token. The handle must have TOKEN_QUERY access to the token. The token must be an impersonation token.

If TokenHandle is NULL, CheckTokenMembership uses the impersonation token of the calling thread. If the thread is not impersonating, the function duplicates the thread's primary token to create an impersonation token.

SidToCheck [in]

A pointer to a SID structure. The CheckTokenMembership function checks for the presence of this SID in the user and group SIDs of the access token.

IsMember [out]

A pointer to a variable that receives the results of the check. If the SID is present and has the SE_GROUP_ENABLED attribute, IsMember returns TRUE; otherwise, it returns FALSE.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The CheckTokenMembership function simplifies the process of determining whether a SID is both present and enabled in an access token.

Even if a SID is present in the token, the system may not use the SID in an access check. The SID may be disabled or have the SE_GROUP_USE_FOR_DENY_ONLY attribute. The system uses only enabled SIDs to grant access when performing an access check. For more information, see SID Attributes in an Access Token.

If TokenHandle is a restricted token, or if TokenHandle is NULL and the current effective token of the calling thread is a restricted token, CheckTokenMembership also checks whether the SID is present in the list of restricting SIDs.

Examples

The following example shows checking a token for membership in the Administrators local group.


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);
}


Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Access Control Overview
Basic Access Control Functions
AccessCheck
CheckTokenMembershipEx
CreateRestrictedToken

 

 

Community Additions

ADD
Show:
© 2014 Microsoft