Función CheckTokenMembership (securitybaseapi.h)

Artículo
03/15/2023

La función CheckTokenMembership determina si un identificador de seguridad (SID) especificado está habilitado en un token de acceso. Si desea determinar la pertenencia a grupos para los tokens de contenedor de aplicaciones, debe usar la función CheckTokenMembershipEx .

Sintaxis

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

Parámetros

[in, optional] TokenHandle

Identificador de un token de acceso. El identificador debe tener TOKEN_QUERY acceso al token. El token debe ser un token de suplantación.

Si TokenHandle es NULL, CheckTokenMembership usa el token de suplantación del subproceso que realiza la llamada. Si el subproceso no suplanta, la función duplica el token principal del subproceso para crear un token de suplantación.

[in] SidToCheck

Puntero a una estructura de SID . La función CheckTokenMembership comprueba la presencia de este SID en los SID de usuario y grupo del token de acceso.

[out] IsMember

Puntero a una variable que recibe los resultados de la comprobación. Si el SID está presente y tiene el atributo SE_GROUP_ENABLED, IsMember devuelve TRUE; de lo contrario, devuelve FALSE.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función CheckTokenMembership simplifica el proceso de determinar si un SID está presente y habilitado en un token de acceso.

Incluso si un SID está presente en el token, es posible que el sistema no use el SID en una comprobación de acceso. El SID se puede deshabilitar o tener el atributo SE_GROUP_USE_FOR_DENY_ONLY . El sistema solo usa SID habilitados para conceder acceso al realizar una comprobación de acceso. Para obtener más información, consulte Atributos de SID en un token de acceso.

Si TokenHandle es un token restringido, o si TokenHandle es NULL y el token efectivo actual del subproceso de llamada es un token restringido, CheckTokenMembership también comprueba si el SID está presente en la lista de SID de restricción de SID.

Ejemplos

En el ejemplo siguiente se muestra la comprobación de un token para la pertenencia al 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 compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll