CheckTokenMembership 함수(securitybaseapi.h)

아티클
08/25/2023

CheckTokenMembership 함수는 액세스 토큰에서 지정된 SID(보안 식별자)를 사용할 수 있는지 여부를 결정합니다. 앱 컨테이너 토큰에 대한 그룹 멤버 자격을 확인하려면 CheckTokenMembershipEx 함수를 사용해야 합니다.

구문

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

매개 변수

[in, optional] TokenHandle

액세스 토큰에 대한 핸들입니다. 핸들에는 토큰에 대한 TOKEN_QUERY 액세스 권한이 있어야 합니다. 토큰은 가장 토큰이어야 합니다.

TokenHandle이 NULL인 경우 CheckTokenMembership은 호출 스레드의 가장 토큰을 사용합니다. 스레드가 가장하지 않는 경우 함수는 스레드의 기본 토큰을 복제하여 가장 토큰을 만듭니다.

[in] SidToCheck

SID 구조체에 대한 포인터입니다. CheckTokenMembership 함수는 액세스 토큰의 사용자 및 그룹 SID에 이 SID가 있는지 확인합니다.

[out] IsMember

검사 결과를 수신하는 변수에 대한 포인터입니다. SID가 있고 SE_GROUP_ENABLED 특성이 있는 경우 IsMember는TRUE를 반환합니다. 그렇지 않으면 FALSE를 반환 합니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

CheckTokenMembership 함수는 SID가 액세스 토큰에 존재하고 사용하도록 설정되어 있는지 여부를 확인하는 프로세스를 간소화합니다.

SID가 토큰에 있더라도 시스템은 액세스 검사 SID를 사용하지 않을 수 있습니다. SID를 사용하지 않도록 설정하거나 SE_GROUP_USE_FOR_DENY_ONLY 특성을 가질 수 있습니다. 시스템은 액세스 검사 수행할 때 활성화된 SID만 사용하여 액세스 권한을 부여합니다. 자세한 내용은 액세스 토큰의 SID 특성을 참조하세요.

TokenHandle이 제한된 토큰이거나 TokenHandle이 NULL이고 호출 스레드의 현재 유효 토큰이 제한된 토큰인 경우 CheckTokenMembership은 SID가 SID 제한 목록에 있는지도 확인합니다.

예제

다음 예제에서는 관리자 로컬 그룹의 멤버 자격에 대한 토큰을 확인하는 방법을 보여 줍니다.

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

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	securitybaseapi.h(Windows.h 포함)
라이브러리	Advapi32.lib
DLL	Advapi32.dll