CheckTokenMembership, fonction (securitybaseapi.h)

Article
08/25/2023

La fonction CheckTokenMembership détermine si un identificateur de sécurité (SID) spécifié est activé dans un jeton d’accès. Si vous souhaitez déterminer l’appartenance au groupe pour les jetons de conteneur d’application, vous devez utiliser la fonction CheckTokenMembershipEx .

Syntaxe

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

Paramètres

[in, optional] TokenHandle

Handle pour un jeton d’accès. Le handle doit avoir TOKEN_QUERY accès au jeton. Le jeton doit être un jeton d’emprunt d’identité.

Si TokenHandle a la valeur NULL, CheckTokenMembership utilise le jeton d’emprunt d’identité du thread appelant. Si le thread n’emprunte pas l’identité, la fonction duplique le jeton principal du thread pour créer un jeton d’emprunt d’identité.

[in] SidToCheck

Pointeur vers une structure SID . La fonction CheckTokenMembership vérifie la présence de ce SID dans les SID d’utilisateur et de groupe du jeton d’accès.

[out] IsMember

Pointeur vers une variable qui reçoit les résultats du case activée. Si le SID est présent et a l’attribut SE_GROUP_ENABLED, IsMember retourne TRUE ; sinon, elle retourne FALSE.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

La fonction CheckTokenMembership simplifie le processus de détermination de la présence et de l’activation d’un SID dans un jeton d’accès.

Même si un SID est présent dans le jeton, le système ne peut pas l’utiliser dans un case activée d’accès. Le SID peut être désactivé ou avoir l’attribut SE_GROUP_USE_FOR_DENY_ONLY . Le système utilise uniquement des SID activés pour accorder l’accès lors de l’exécution d’un case activée d’accès. Pour plus d’informations, consultez Attributs SID dans un jeton d’accès.

Si TokenHandle est un jeton restreint, ou si TokenHandle a la valeur NULL et que le jeton effectif actuel du thread appelant est un jeton restreint, CheckTokenMembership vérifie également si le SID est présent dans la liste des SID restrictifs.

Exemples

L’exemple suivant montre la vérification d’un jeton pour l’appartenance au groupe local Administrateurs.

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

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll