Fungsi CheckTokenMembership (securitybaseapi.h)

Artikel
08/25/2023

Fungsi CheckTokenMembership menentukan apakah pengidentifikasi keamanan (SID) tertentu diaktifkan dalam token akses. Jika Anda ingin menentukan keanggotaan grup untuk token kontainer aplikasi, Anda perlu menggunakan fungsi CheckTokenMembershipEx .

Sintaks

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

Parameter

[in, optional] TokenHandle

Handel ke token akses. Handel harus memiliki akses TOKEN_QUERY ke token. Token harus berupa token peniruan.

Jika TokenHandleNULL, CheckTokenMembership menggunakan token peniruan utas panggilan. Jika utas tidak meniru, fungsi akan menduplikasi token utama utas untuk membuat token peniruan.

[in] SidToCheck

Penunjuk ke struktur SID . Fungsi CheckTokenMembership memeriksa keberadaan SID ini di pengguna dan mengelompokkan SID token akses.

[out] IsMember

Pointer ke variabel yang menerima hasil pemeriksaan. Jika SID ada dan memiliki atribut SE_GROUP_ENABLED, IsMember mengembalikan TRUE; jika tidak, ia mengembalikan FALSE.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi CheckTokenMembership menyederhanakan proses penentuan apakah SID ada dan diaktifkan dalam token akses.

Bahkan jika SID ada dalam token, sistem mungkin tidak menggunakan SID dalam pemeriksaan akses. SID dapat dinonaktifkan atau memiliki atribut SE_GROUP_USE_FOR_DENY_ONLY . Sistem hanya menggunakan SID yang diaktifkan untuk memberikan akses saat melakukan pemeriksaan akses. Untuk informasi selengkapnya, lihat Atribut SID dalam Token Akses.

Jika TokenHandle adalah token terbatas, atau jika TokenHandleadalah NULL dan token efektif saat ini dari utas panggilan adalah token terbatas, CheckTokenMembership juga memeriksa apakah SID ada dalam daftar MEMBATASI SID.

Contoh

Contoh berikut menunjukkan pemeriksaan token untuk keanggotaan di grup lokal Administrator.

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

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	securitybaseapi.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll