CheckTokenMembership

[This is preliminary documentation and subject to change.]

The CheckTokenMembership function determines whether a specified SID is enabled in an access token.

BOOL CheckTokenMembership(
  HANDLE TokenHandle,  // handle to an access token
  PSID SidToCheck,     // SID to check for 
  PBOOL IsMember       // receives results of the check 
);
 

Parameters

TokenHandle

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

Pointer to a SID. CheckTokenMembership checks for the presence of this SID in the user and group SIDs of the access token.

IsMember

Pointer to a BOOL 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 Values

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.

Just because a SID is present in the token, doesn't mean that the system will use it 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.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use advapi32.lib.

See Also

Access Control Overview, Access Control Functions, AccessCheck, CreateRestrictedToken