CheckTokenMembership-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die CheckTokenMembership-Funktion bestimmt, ob eine angegebene Sicherheits-ID (SID) in einem Zugriffstoken aktiviert ist. Wenn Sie die Gruppenmitgliedschaft für App-Containertoken ermitteln möchten, müssen Sie die CheckTokenMembershipEx-Funktion verwenden.

Syntax

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

Parameter

[in, optional] TokenHandle

Ein Handle für ein Zugriffstoken. Das Handle muss TOKEN_QUERY Zugriff auf das Token haben. Das Token muss ein Identitätswechseltoken sein.

Wenn TokenHandleNULL ist, verwendet CheckTokenMembership das Identitätswechseltoken des aufrufenden Threads. Wenn der Thread keine Identitätswechsel aufweist, dupliziert die Funktion das primäre Token des Threads, um ein Identitätswechseltoken zu erstellen.

[in] SidToCheck

Ein Zeiger auf eine SID-Struktur . Die CheckTokenMembership-Funktion überprüft, ob diese SID in den Benutzer- und Gruppen-SIDs des Zugriffstokens vorhanden ist.

[out] IsMember

Ein Zeiger auf eine Variable, die die Ergebnisse der Überprüfung empfängt. Wenn die SID vorhanden ist und über das Attribut SE_GROUP_ENABLED verfügt, gibt IsMemberTRUE zurück. Andernfalls wird FALSE zurückgegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die CheckTokenMembership-Funktion vereinfacht die Ermittlung, ob eine SID in einem Zugriffstoken vorhanden und aktiviert ist.

Auch wenn eine SID im Token vorhanden ist, verwendet das System die SID möglicherweise nicht bei einer Zugriffsüberprüfung. Die SID kann deaktiviert sein oder das Attribut SE_GROUP_USE_FOR_DENY_ONLY aufweisen. Das System verwendet nur aktivierte SIDs, um den Zugriff bei einer Zugriffsüberprüfung zu gewähren. Weitere Informationen finden Sie unter SID-Attribute in einem Zugriffstoken.

Wenn TokenHandle ein eingeschränktes Token ist oder TokenHandleNULL ist und das aktuelle effektive Token des aufrufenden Threads ein eingeschränktes Token ist, überprüft CheckTokenMembership auch, ob die SID in der Liste der einschränkenden SIDs vorhanden ist.

Beispiele

Das folgende Beispiel zeigt die Überprüfung eines Tokens für die Mitgliedschaft in der lokalen Gruppe Administratoren.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll